OpenAPI Docs and Client code generation for Spring Boot applications

openapi-docs-client-generation-spring-boot.md

Environment

• Spring Boot 2.x
• Gradle
• Java

Steps

Step1: Enable springdoc-openapi in app

Add the following dependency in build.gradle.

dependencies {
  ..
  implementation 'org.springdoc:springdoc-openapi-ui:1.2.33'
  ..
}

Step2: Enable springdoc-openapi-gradle-plugin

Add the following plugin in bulid.gradle.

plugins {
  ..
  id "com.github.johnrengelman.processes" version "0.5.0"
  id("org.springdoc.openapi-gradle-plugin") version "1.0.0"
  ..
}

Step3: Run generateOpenApiDocs task

$ ./gradlew generateOpenApiDocs

When this task is called, a background task to run the app will be called internally. Therefore, if your app needs some environment variables, you need to specify them in this invocation.

The default output file path is ${buildDir}/openapi.json.

Step4: Enable openapi-generator gradle plugin

plugins {
  ..
  id "org.openapi.generator" version "4.2.3"
  ..
}

Step5: Add client code generation config

Add the following config to build.gradle. This config specifies the output type of typescript-axios.

openApiGenerate {
    generatorName = "typescript-axios"
    inputSpec = "${buildDir}/openapi.json";
    outputDir = "${buildDir}/frontend/src/app/client"
}

Step6: Print applicable output types

$ ./gradlew openApiGenerators

The result is shown in Appendix.

Step7: Run openApiGenerate task

$ ./gradlew openApiGenerate

References

• https://github.com/springdoc/springdoc-openapi
• https://github.com/springdoc/springdoc-openapi-gradle-plugin
• https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-gradle-plugin
• https://qiita.com/chibato/items/e4a748db12409b40c02f

Appendix: result of openApiGenerators

The following generators are available:

CLIENT generators:
    - ada
    - android
    - apex
    - bash
    - c
    - clojure
    - cpp-qt5-client
    - cpp-restsdk
    - cpp-tizen
    - csharp
    - csharp-netcore
    - dart
    - dart-dio
    - dart-jaguar
    - eiffel
    - elixir
    - elm
    - erlang-client
    - erlang-proper
    - flash
    - go
    - go-experimental (experimental)
    - groovy
    - haskell-http-client
    - java
    - javascript
    - javascript-closure-angular
    - javascript-flowtyped
    - jaxrs-cxf-client
    - jmeter
    - kotlin
    - lua
    - nim (beta)
    - objc
    - ocaml
    - perl
    - php
    - powershell
    - python
    - python-experimental (experimental)
    - r
    - ruby
    - rust
    - scala-akka
    - scala-gatling
    - scalaz
    - swift4
    - swift5 (beta)
    - typescript-angular
    - typescript-angularjs
    - typescript-aurelia
    - typescript-axios
    - typescript-fetch
    - typescript-inversify
    - typescript-jquery
    - typescript-node
    - typescript-redux-query
    - typescript-rxjs


SERVER generators:
    - ada-server
    - aspnetcore
    - cpp-pistache-server
    - cpp-qt5-qhttpengine-server
    - cpp-restbed-server
    - csharp-nancyfx
    - erlang-server
    - fsharp-functions (beta)
    - fsharp-giraffe-server (beta)
    - go-gin-server
    - go-server
    - graphql-nodejs-express-server
    - haskell
    - java-inflector
    - java-msf4j
    - java-pkmst
    - java-play-framework
    - java-undertow-server
    - java-vertx
    - java-vertx-web (beta)
    - jaxrs-cxf
    - jaxrs-cxf-cdi
    - jaxrs-cxf-extended
    - jaxrs-jersey
    - jaxrs-resteasy
    - jaxrs-resteasy-eap
    - jaxrs-spec
    - kotlin-server
    - kotlin-spring
    - kotlin-vertx (beta)
    - nodejs-express-server (beta)
    - php-laravel
    - php-lumen
    - php-silex
    - php-slim4
    - php-symfony
    - php-ze-ph
    - python-aiohttp
    - python-blueplanet
    - python-flask
    - ruby-on-rails
    - ruby-sinatra
    - rust-server
    - scala-finch
    - scala-lagom-server
    - scala-play-server
    - scalatra
    - spring


DOCUMENTATION generators:
    - asciidoc
    - cwiki
    - dynamic-html
    - html
    - html2
    - markdown (beta)
    - openapi
    - openapi-yaml


SCHEMA generators:
    - avro-schema (beta)
    - mysql-schema


CONFIG generators:
    - apache2
    - graphql-schema
    - protobuf-schema (beta)


OTHER generators:

Just one addition, in my project I wanted to build clients in multiple languages, which will be used by several other web-apps.

So I created custom tasks :

task openApiGenerateJavaClient(type: org.openapitools.generator.gradle.plugin.tasks.GenerateTask) {
    inputSpec = "$buildDir/openapi.json";
    outputDir = "${buildDir}/clients/java/"

    generatorName = "java"

    groupId = group

    apiPackage = "bike.rapido.ingestion.gateway.client.api"
    invokerPackage = "bike.rapido.ingestion.gateway.client.invoker"
    modelPackage = "bike.rapido.ingestion.gateway.client.model"

    configOptions = [
            library        : "feign",
            dateLibrary    : "java8",
            artifactId     : "ingestion-gateway-client",
            artifactVersion: project.version.toString(),
    ]
}


task openApiGenerateNodeClient(type: org.openapitools.generator.gradle.plugin.tasks.GenerateTask) {

    inputSpec = "$buildDir/openapi.json";
    outputDir = "${buildDir}/clients/javascript/"

    generatorName = "javascript"

    groupId = group

    apiPackage = "api"
    invokerPackage = "invoker"
    modelPackage = "model"

    configOptions = [
            usePromises: "true",
            projectName: "ingestion-gateway-client",
    ]

}