Version 4 - navigation aids in routes; improvements; new OpenAPI generator

Author: ianthetechie

CHANGELOG.md

@@ -5,6 +5,50 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Version 4.0.0 - 2025-01-27
+
+### Added
+
+- Adds support for the OSRM format and navigation aids.
+- Explicitly documented more properties on the geocoding feature model.
+- Adds support for the `foursquare` data source.
+- Documents the elevation interval parameter on certain routing requests.
+
+### Changed
+
+- BREAKING: This unfortunately means that some properties of the route response model, due to how the OpenAPI generator handles these models (it does not know how to generate variant models yet).
+- BREAKING: Renamed models containing Valhalla and Pelias in their names to be generic. These now have rout(e|ing) or geocod(e|ing) prefixes.
+- BREAKING: Removed one layer of nesting in the API namespace.
+- Switched to [OpenAPI Generator](https://openapi-generator.tech/docs/generators/kotlin/) as the previous plugin appears to be abandoned.
+
+### Migration notes
+
+#### Imports
+
+API imports have changed slightly, removing one level of nesting.
+Simply remove the `apis` package from the path like so:
+
+```diff
+- import com.stadiamaps.api.apis.GeocodingApi
++ import com.stadiamaps.api.GeocodingApi
+```
+
+#### Renamed types
+
+Several geocoding and routing types have been renamed to reflect their purpose better.
+All types beginning with `Pelias` (e.g. `PeliasLayer`) now have a `Geocoding` prefix (e.g. `GeocodingLayer`).
+Similarly, all types with a `Valhalla` prefix (e.g. `ValhallaLanguage`) now have a `Routing` prefix (e.g. `RoutingLanguage`). 
+
+#### Routing API model changes
+
+Some properties of `Route200Response` are now optional.
+This is due to a bug in the OpenAPI generator for Kotlin,
+which coalesces all properties into a single model rather than having two variations on the model based on format.
+When requesting a route with navigation aids (`format = RouteRequest.Format.osrm`),
+the `routes` property will contain the enhanced route information.
+Existing code using the original compact format will continue using the `trip` property.
+When you receive a successful response, your code can safely use the nun-null assertion operator (`!!`).
+
 ## Version 3.2.1 - 2024-08-15
 
 ### Fixed

RELEASE.md

@@ -19,4 +19,3 @@ To export the private key, you can run the following command (requires passphara
 ```shell
 gpg --output mavencentral.pgp --armor --export-secret-key you@example.com
 ```
-

example/src/main/kotlin/Main.kt

@@ -1,6 +1,6 @@
-import com.stadiamaps.api.apis.GeocodingApi
-import com.stadiamaps.api.apis.GeospatialApi
-import com.stadiamaps.api.apis.RoutingApi
+import com.stadiamaps.api.GeocodingApi
+import com.stadiamaps.api.GeospatialApi
+import com.stadiamaps.api.RoutingApi
 import com.stadiamaps.api.auth.ApiKeyAuth
 import com.stadiamaps.api.infrastructure.ApiClient
 import com.stadiamaps.api.models.*

generated-client/build.gradle.kts

@@ -1,19 +1,31 @@
+buildscript {
+    repositories {
+        mavenCentral()
+    }
+    dependencies {
+        classpath("org.yaml:snakeyaml:2.0")
+    }
+}
+
 import org.gradle.api.DefaultTask
 import org.gradle.api.tasks.Input
 import org.gradle.api.tasks.OutputFile
 import org.gradle.api.tasks.TaskAction
-import org.hidetake.gradle.swagger.generator.GenerateSwaggerCode
+
+import org.yaml.snakeyaml.Yaml
+import org.yaml.snakeyaml.constructor.SafeConstructor
 
 plugins {
     kotlin("jvm")
-    id("org.hidetake.swagger.generator") version "2.19.2"
+    id("org.openapi.generator") version "7.11.0"
     `maven-publish`
     signing
     id("org.jetbrains.dokka") version "1.9.20"
     id("tech.yanand.maven-central-publish") version "1.1.1"
 }
 
 val stagingDir = layout.buildDirectory.dir("staging-deploy").get()
+val generatedClientDir = layout.buildDirectory.dir("generated").get()
 
 repositories {
     mavenCentral()
@@ -22,8 +34,6 @@ repositories {
 dependencies {
     val retrofitVersion: String by project
 
-    swaggerCodegen("org.openapitools:openapi-generator-cli:7.5.0")
-
     // Dependencies of the generated code. Check out `build.gradle` in your build folder later if you're curious.
     val moshiVersion = "1.15.1"
     implementation("com.squareup.moshi:moshi-kotlin:$moshiVersion")
@@ -70,23 +80,58 @@ tasks.register("downloadOpenAPISpec", DownloadResource::class.java) {
     target = File("openapi.yaml")
 }
 
-tasks.named("generateSwaggerCode").configure {
+tasks.register("patchOpenAPISpec") {
+    doLast {
+        val openApiFile = file("openapi.yaml")
+        val originalText = openApiFile.readText()
+
+        // We have to do some post-processing of the YAML spec here,
+        // because of https://github.com/OpenAPITools/openapi-generator/issues/18167.
+        // The way the Kotlin OpenAPI generator works for `oneOf` models,
+        // the result is a superset of all the properties of the
+
+        // Parse the document with SnakeYAML
+        val yaml = Yaml()
+        val root = yaml.load<Map<String, Any>>(originalText)?.toMutableMap() ?: mutableMapOf()
+
+        // Remove the required Valhalla route response properties (trip in this case)
+        val components = (root["components"] as? Map<*, *>)!!.toMutableMap()
+        val schemas = (components["schemas"] as? Map<*, *>)!!.toMutableMap()
+
+        val routeResponse = (schemas["routeResponse"] as? Map<*, *>)!!.toMutableMap()
+        routeResponse.remove("required")
+        schemas["routeResponse"] = routeResponse
+
+        val osrmBaseApiResponse = (schemas["osrmBaseApiResponse"] as? Map<*, *>)!!.toMutableMap()
+        osrmBaseApiResponse.remove("required")
+        schemas["osrmBaseApiResponse"] = osrmBaseApiResponse
+
+        components["schemas"] = schemas
+        root["components"] = components
+
+        openApiFile.writeText(yaml.dump(root))
+
+    }
+}
+
+tasks.named("patchOpenAPISpec").configure {
     dependsOn("downloadOpenAPISpec")
 }
 
+tasks.named("openApiGenerate").configure {
+    dependsOn("patchOpenAPISpec")
+}
+
 tasks.named<Jar>("sourcesJar").configure {
-    dependsOn("generateSwaggerCode")
+    dependsOn("openApiGenerate")
 }
 
 tasks.dokkaHtml {
-    dependsOn("generateSwaggerCode")
-    outputDirectory.set(buildDir.resolve("dokkaHtml"))
+    dependsOn("openApiGenerate")
+    outputDirectory.set(layout.buildDirectory.dir("dokkaHtml"))
     dokkaSourceSets {
         configureEach {
-            includeNonPublic.set(false)
             reportUndocumented.set(true)
-            skipEmptyPackages.set(true)
-            skipDeprecated.set(false)
             jdkVersion.set(11)
         }
     }
@@ -98,31 +143,26 @@ tasks.register<Jar>("dokkaJavadocJar") {
     from(tasks.dokkaHtml)
 }
 
-swaggerSources {
-  register("stadiamaps") {
-      val validationTask = validation
-      validationTask.dependsOn("downloadOpenAPISpec")
-
-      setInputFile(file("openapi.yaml"))
-      code(delegateClosureOf<GenerateSwaggerCode> {
-          language = "kotlin"
-          library = "jvm-retrofit2"
-          additionalProperties = mapOf("groupId" to "com.stadiamaps", "packageName" to "com.stadiamaps.api")
-          dependsOn(validationTask)
-      })
-  }
+openApiGenerate {
+    generatorName.set("kotlin")
+    library.set("jvm-retrofit2")
+    groupId.set("com.stadiamaps")
+    inputSpec.set(file("openapi.yaml").path)
+    apiPackage.set("com.stadiamaps.api")
+    packageName.set("com.stadiamaps.api")
+    modelPackage.set("com.stadiamaps.api.models")
+    outputDir.set(generatedClientDir.toString())
 }
 
 // Comment this out if you do NOT want the code gen to run every time you build.
 // There is an HTTP cache by default, so it won't necessarily make a request every single build.
 tasks.compileKotlin.configure {
-    dependsOn(tasks.generateSwaggerCode)
+    dependsOn(tasks.openApiGenerate)
 }
 
 sourceSets {
     val main by getting
-    val stadiamaps by swaggerSources.getting
-    main.kotlin.srcDir("${stadiamaps.code.outputDir}/src/main/kotlin")
+    main.kotlin.srcDir("${generatedClientDir}/src/main/kotlin")
 }
 
 publishing {
@@ -145,7 +185,7 @@ publishing {
         create<MavenPublication>("publication") {
             groupId = "com.stadiamaps"
             artifactId = "api"
-            version = "3.2.1"
+            version = "4.0.0"
 
             from(components["java"])