How to externalize some parts of an API specification?

[jdaugherty]

It's amazing that we can annotate classes and generate a full API specification, but if a lengthy description is added to the @Info annotation of the @OpenAPIDefinition it can become troublesome to maintain. An example of this is here. Is it possible to externalize parts of the OpenAPI definition so that those lengthy parts can be stored in a yml file?

This is possible in a Grails / Spring Boot application by using the gradle plugin io.swagger.core.v3.swagger-gradle-plugin. Defining something like this in the build.gradle file:

tasks.register('updateOpenAPIVersion', Copy) {
    from "openapi.yaml"
    into "$buildDir/tmp"
    filter { line -> line.replaceAll('API_VERSION', project.version) }
}
resolve {
    dependsOn(tasks.updateOpenAPIVersion, classes)
    classpath = sourceSets.main.runtimeClasspath
    outputDir = file("$buildDir/resources/main/openapi")
    outputFileName = 'my-api-definition'
    openApiFile = file("$buildDir/tmp/openapi.yaml")
    outputFormat = 'YAML'
    resourcePackages = ['com.example']
    readAllResources = false
    prettyPrint = true
}

In addition to the above, a file called 'openapi.yaml' would exist at the root of the project. This file could then contain something like this:

openapi: 3.0.1
info:
  title: My API
  description: |
    # Purpose
    A lengthy purpose introduction.

    # Another title
    Some more information.

    # Yet another title
    And more information
  version: 1.0.0

With the above gradle configuration & a yaml file, when the swagger documentation is generated via the gradle resolve command, it would combine the generated documentation from the used annotations with that file (In this example, @OpenAPIDefinition would not be defined in the application, it would come from the yaml file).

For maintainers of larger API specifications that add additional data to the description section, this is extremely useful. Tools like redoc can break up this description into separate sections of your api documentation.

Are there any solutions similar to the swagger gradle plugin with spring, but for a micronaut application?

[altro3]

Read documenttion, please. You can use placeholdores in annotations and set these properties as you wish:

• as system properties
• as env variables
• in application.yml
• in openapi.properties file