Generate API models with openapi-generator plugin in new module (#992)

build.gradle

@@ -30,6 +30,7 @@ buildscript {
 
 plugins {
     id "com.github.ben-manes.versions" version "0.42.0"
+    id "org.openapi.generator" version "7.10.0"
 }
 
 allprojects {

settings.gradle

@@ -1,2 +1,3 @@
 include ':libTba', ':libImgur'
-include 'android'
+include 'android'
+include ':tba-api'

tba-api/.gitignore

@@ -0,0 +1,2 @@
+/build
+.openapi-generator

tba-api/README.md

@@ -0,0 +1,12 @@
+# tba-api
+This module is intended to replace `:libTba`. `:libTba` is a generated set of TBA API models
+using [a fork of swagger-codegen](https://github.com/the-blue-alliance/swagger-codegen) to support
+features such as generating interfaces instead of concrete classes. That fork has not been updated
+in some time, and is no longer compatible with the latest swagger specs.
+
+This module aims to use [openapi-generator](https://github.com/OpenAPITools/openapi-generator) as-is
+to generate concrete classes. This should more easily facilitate updates to the plugin and swagger
+specs in the future, decreasing maintenance overhead.
+
+## Updating generated models & API interfaces
+To update the generated API models and Retrofit API interfaces, run `./gradlew tba-api:openApiGenerate`.

tba-api/build.gradle

@@ -0,0 +1,50 @@
+plugins {
+    id 'java-library'
+    id "org.openapi.generator" version "7.10.0"
+}
+
+java {
+    sourceCompatibility = JavaVersion.VERSION_1_8
+    targetCompatibility = JavaVersion.VERSION_1_8
+}
+
+openApiGenerate {
+    generatorName.set("java")
+    remoteInputSpec.set("https://www.thebluealliance.com/swagger/api_v3.json")
+    outputDir.set("$projectDir")
+    apiPackage.set("thebluealliance.api")
+    invokerPackage.set("thebluealliance.api.client")
+    modelPackage.set("thebluealliance.api.model")
+
+    // We don't need the generated markdown docs, or tests
+    generateApiDocumentation.set(false)
+    generateModelDocumentation.set(false)
+    generateApiTests.set(false)
+    generateModelTests.set(false)
+
+    // By default the generator creates a full project, including a github workflow,
+    // gradle build files, etc.
+    // Remove all that except the generated Java files, and a couple of support files that are referenced
+    globalProperties.set([
+            apis           : "",
+            models         : "",
+            supportingFiles: "CollectionFormats.java,StringUtil.java",
+    ])
+
+    // We don't currently use the generated Retrofit interface because we are still on RxJava 1.x
+    // In the future we can set configOptions.put("useRxJava2", "true")
+    // and use the generated Retrofit interfaces as well.
+    configOptions.put("library", "retrofit2")
+    configOptions.put("serializationLibrary", "gson")
+}
+
+dependencies {
+    // in java 9+ java.annotation.Generated moved to java.annotation.processing.Generated
+    // so use this lib for back-compat
+    implementation "javax.annotation:javax.annotation-api:1.3.2"
+    implementation 'org.openapitools:jackson-databind-nullable:0.2.6'
+    implementation "io.reactivex:rxjava:${rxJavaVersion}"
+    implementation "com.squareup.retrofit2:retrofit:${retrofitVersion}"
+    implementation "com.google.code.gson:gson:${gsonVersion}"
+    implementation "com.google.code.findbugs:jsr305:3.0.2"
+}

tba-api/src/main/java/thebluealliance/api/DefaultApi.java

@@ -0,0 +1,34 @@
+package thebluealliance.api;
+
+import thebluealliance.api.client.CollectionFormats.*;
+
+import retrofit2.Call;
+import retrofit2.http.*;
+
+import okhttp3.RequestBody;
+import okhttp3.ResponseBody;
+import okhttp3.MultipartBody;
+
+import thebluealliance.api.model.GetStatus401Response;
+import thebluealliance.api.model.SearchIndex;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+public interface DefaultApi {
+  /**
+   * 
+   * Gets a large blob of data that is used on the frontend for searching. May change without notice.
+   * @param year Competition Year (or Season). Must be 4 digits. (required)
+   * @param ifNoneMatch Value of the `ETag` header in the most recently cached response by the client. (optional)
+   * @return Call<SearchIndex>
+   */
+  @GET("search_index")
+  Call<SearchIndex> getSearchIndex(
+    @retrofit2.http.Path("year") Integer year, @retrofit2.http.Header("If-None-Match") String ifNoneMatch
+  );
+
+}

tba-api/src/main/java/thebluealliance/api/DistrictApi.java

@@ -0,0 +1,173 @@
+package thebluealliance.api;
+
+import thebluealliance.api.client.CollectionFormats.*;
+
+import retrofit2.Call;
+import retrofit2.http.*;
+
+import okhttp3.RequestBody;
+import okhttp3.ResponseBody;
+import okhttp3.MultipartBody;
+
+import thebluealliance.api.model.Award;
+import thebluealliance.api.model.DistrictList;
+import thebluealliance.api.model.DistrictRanking;
+import thebluealliance.api.model.Event;
+import thebluealliance.api.model.EventDistrictPoints;
+import thebluealliance.api.model.EventSimple;
+import thebluealliance.api.model.GetStatus401Response;
+import thebluealliance.api.model.Team;
+import thebluealliance.api.model.TeamSimple;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+public interface DistrictApi {
+  /**
+   * 
+   * Gets a list of awards in the given district.
+   * @param districtKey TBA District Key, eg `2016fim` (required)
+   * @param ifNoneMatch Value of the `ETag` header in the most recently cached response by the client. (optional)
+   * @return Call<List<Award>>
+   */
+  @GET("district/{district_key}/awards")
+  Call<List<Award>> getDistrictAwards(
+    @retrofit2.http.Path("district_key") String districtKey, @retrofit2.http.Header("If-None-Match") String ifNoneMatch
+  );
+
+  /**
+   * 
+   * Gets a list of events in the given district.
+   * @param districtKey TBA District Key, eg &#x60;2016fim&#x60; (required)
+   * @param ifNoneMatch Value of the &#x60;ETag&#x60; header in the most recently cached response by the client. (optional)
+   * @return Call&lt;List&lt;Event&gt;&gt;
+   */
+  @GET("district/{district_key}/events")
+  Call<List<Event>> getDistrictEvents(
+    @retrofit2.http.Path("district_key") String districtKey, @retrofit2.http.Header("If-None-Match") String ifNoneMatch
+  );
+
+  /**
+   * 
+   * Gets a list of event keys for events in the given district.
+   * @param districtKey TBA District Key, eg &#x60;2016fim&#x60; (required)
+   * @param ifNoneMatch Value of the &#x60;ETag&#x60; header in the most recently cached response by the client. (optional)
+   * @return Call&lt;List&lt;String&gt;&gt;
+   */
+  @GET("district/{district_key}/events/keys")
+  Call<List<String>> getDistrictEventsKeys(
+    @retrofit2.http.Path("district_key") String districtKey, @retrofit2.http.Header("If-None-Match") String ifNoneMatch
+  );
+
+  /**
+   * 
+   * Gets a short-form list of events in the given district.
+   * @param districtKey TBA District Key, eg &#x60;2016fim&#x60; (required)
+   * @param ifNoneMatch Value of the &#x60;ETag&#x60; header in the most recently cached response by the client. (optional)
+   * @return Call&lt;List&lt;EventSimple&gt;&gt;
+   */
+  @GET("district/{district_key}/events/simple")
+  Call<List<EventSimple>> getDistrictEventsSimple(
+    @retrofit2.http.Path("district_key") String districtKey, @retrofit2.http.Header("If-None-Match") String ifNoneMatch
+  );
+
+  /**
+   * 
+   * Gets a list of District objects with the given district abbreviation. This accounts for district abbreviation changes, such as MAR to FMA.
+   * @param districtAbbreviation District abbreviation, eg &#x60;ne&#x60; or &#x60;fim&#x60; (required)
+   * @param ifNoneMatch Value of the &#x60;ETag&#x60; header in the most recently cached response by the client. (optional)
+   * @return Call&lt;List&lt;DistrictList&gt;&gt;
+   */
+  @GET("district/{district_abbreviation}/history")
+  Call<List<DistrictList>> getDistrictHistory(
+    @retrofit2.http.Path("district_abbreviation") String districtAbbreviation, @retrofit2.http.Header("If-None-Match") String ifNoneMatch
+  );
+
+  /**
+   * 
+   * Gets a list of team district rankings for the given district.
+   * @param districtKey TBA District Key, eg &#x60;2016fim&#x60; (required)
+   * @param ifNoneMatch Value of the &#x60;ETag&#x60; header in the most recently cached response by the client. (optional)
+   * @return Call&lt;List&lt;DistrictRanking&gt;&gt;
+   */
+  @GET("district/{district_key}/rankings")
+  Call<List<DistrictRanking>> getDistrictRankings(
+    @retrofit2.http.Path("district_key") String districtKey, @retrofit2.http.Header("If-None-Match") String ifNoneMatch
+  );
+
+  /**
+   * 
+   * Gets a list of &#x60;Team&#x60; objects that competed in events in the given district.
+   * @param districtKey TBA District Key, eg &#x60;2016fim&#x60; (required)
+   * @param ifNoneMatch Value of the &#x60;ETag&#x60; header in the most recently cached response by the client. (optional)
+   * @return Call&lt;List&lt;Team&gt;&gt;
+   */
+  @GET("district/{district_key}/teams")
+  Call<List<Team>> getDistrictTeams(
+    @retrofit2.http.Path("district_key") String districtKey, @retrofit2.http.Header("If-None-Match") String ifNoneMatch
+  );
+
+  /**
+   * 
+   * Gets a list of &#x60;Team&#x60; objects that competed in events in the given district.
+   * @param districtKey TBA District Key, eg &#x60;2016fim&#x60; (required)
+   * @param ifNoneMatch Value of the &#x60;ETag&#x60; header in the most recently cached response by the client. (optional)
+   * @return Call&lt;List&lt;String&gt;&gt;
+   */
+  @GET("district/{district_key}/teams/keys")
+  Call<List<String>> getDistrictTeamsKeys(
+    @retrofit2.http.Path("district_key") String districtKey, @retrofit2.http.Header("If-None-Match") String ifNoneMatch
+  );
+
+  /**
+   * 
+   * Gets a short-form list of &#x60;Team&#x60; objects that competed in events in the given district.
+   * @param districtKey TBA District Key, eg &#x60;2016fim&#x60; (required)
+   * @param ifNoneMatch Value of the &#x60;ETag&#x60; header in the most recently cached response by the client. (optional)
+   * @return Call&lt;List&lt;TeamSimple&gt;&gt;
+   */
+  @GET("district/{district_key}/teams/simple")
+  Call<List<TeamSimple>> getDistrictTeamsSimple(
+    @retrofit2.http.Path("district_key") String districtKey, @retrofit2.http.Header("If-None-Match") String ifNoneMatch
+  );
+
+  /**
+   * 
+   * Gets a list of districts and their corresponding district key, for the given year.
+   * @param year Competition Year (or Season). Must be 4 digits. (required)
+   * @param ifNoneMatch Value of the &#x60;ETag&#x60; header in the most recently cached response by the client. (optional)
+   * @return Call&lt;List&lt;DistrictList&gt;&gt;
+   */
+  @GET("districts/{year}")
+  Call<List<DistrictList>> getDistrictsByYear(
+    @retrofit2.http.Path("year") Integer year, @retrofit2.http.Header("If-None-Match") String ifNoneMatch
+  );
+
+  /**
+   * 
+   * Gets a list of team rankings for the Event.
+   * @param eventKey TBA Event Key, eg &#x60;2016nytr&#x60; (required)
+   * @param ifNoneMatch Value of the &#x60;ETag&#x60; header in the most recently cached response by the client. (optional)
+   * @return Call&lt;EventDistrictPoints&gt;
+   */
+  @GET("event/{event_key}/district_points")
+  Call<EventDistrictPoints> getEventDistrictPoints(
+    @retrofit2.http.Path("event_key") String eventKey, @retrofit2.http.Header("If-None-Match") String ifNoneMatch
+  );
+
+  /**
+   * 
+   * Gets an array of districts representing each year the team was in a district. Will return an empty array if the team was never in a district.
+   * @param teamKey TBA Team Key, eg &#x60;frc254&#x60; (required)
+   * @param ifNoneMatch Value of the &#x60;ETag&#x60; header in the most recently cached response by the client. (optional)
+   * @return Call&lt;List&lt;DistrictList&gt;&gt;
+   */
+  @GET("team/{team_key}/districts")
+  Call<List<DistrictList>> getTeamDistricts(
+    @retrofit2.http.Path("team_key") String teamKey, @retrofit2.http.Header("If-None-Match") String ifNoneMatch
+  );
+
+}