Generate a Java OpenAPI client and publish it to S3 using Gradle

How teams at MailSlurp publish and consume client libraries that are generated for each microservice in our cluster.

You can document APIs and generate strongly-typed client libraries automatically using Gradle.

Many teams use OpenAPI to document and consume API services. Using OpenAPI tools we can generate strongly typed clients in a wide range of languages. We can then call other services without needing to maintain type definitions in multiple projects.

With Gradle and Spring we can automate the generation and publication of Swagger codegen clients and distribute the packages via AWS S3. This will give us a private artifact repository that we can connect to in calling services.

Annotate your API endpoints

The first step in automating your API client generation is to annotate your API endpoints and generate an OpenAPI spec. In Spring we can use springdoc-openapi to describe our endpoints. In a build.gradle.kt file add:

dependencies {
    implementation("org.springdoc:springdoc-openapi-ui:1.6.11")
}

Then add annotations to your controllers:

@Operation(operationId = "deleteJob", summary = "Delete a scheduled job") @ResponseStatus(HttpStatus.NO_CONTENT) @DeleteMapping("/jobs/{groupId}/{jobId}") fun deleteJob(@PathVariable("groupId") groupId: String, @PathVariable("jobId") jobId: String) {     schedulerFactory.scheduler.deleteJob(JobKey.jobKey(groupId, jobId)) }

Generate an openapi.json spec

Next we can use gradle to generate a spec:

plugins {  id("org.springdoc.openapi-gradle-plugin") version "1.4.0"  id("org.openapi.generator") version "6.1.0" }

Define a custom openApi task to start Spring and write the OpenAPI spec to the build directory.

openApi { customBootRun { args.set(listOf("--spring.profiles.active=openapi")) } }

When we run ./gradlew generateOpenApiDocs an openapi.json file will be written to the build directory.

Generate a client

Now we can generate an OpenAPI client using a gradle task:

openApiGenerate { generatorName.set("java") version.set(System.getenv("CLIENT_VERSION")) id.set("yourid") groupId.set("yourgroup") inputSpec.set("$buildDir/openapi.json") outputDir.set("$buildDir/client") configOptions.set(mapOf( "dateLibrary" to "java8" )) }

Run the command like so ./gradlew openApiGenerate to write a client into the build/client directory. Next we will publish the client to maven via S3.

Create a maven S3 repository

Create an S3 bucket to use as your maven repository. Now we can publish to S3 with Gradle.

Publish to S3 using Gradle

We can now use a gradle init script to patch the generated gradle client and add a publishing method for our S3 bucket.

allprojects { apply plugin: 'java' apply plugin: 'maven-publish' publishing { publications { mavenJava(MavenPublication) { from components.java } } repositories { maven { url "s3://my.private.maven" authentication { awsIm(AwsImAuthentication) } } } } }

Then to run:

cp init-client.gradle build/client/init-client.gradle cd build/client && ./gradlew --init-script init.gradle publish && cd -

Voila

After this we have shown how to describe your API, generate a client, and publish to S3.

Originally published at https://www.mailslurp.com.