OpenAPI management

A module to provide an OpenAPI file from an application, as well as Swagger UI and Rapidoc for displaying OpenAPI.

Dependency¶

Java Kotlin

Dependency build.gradle:

implementation "ru.tinkoff.kora:openapi-management"

Module:

@KoraApp
public interface Application extends OpenApiManagementModule { }

Dependency build.gradle.kts:

implementation("ru.tinkoff.kora:openapi-management")

Module:

@KoraApp
interface Application : OpenApiManagementModule

Requires HTTP server module.

Configuration¶

An example of the configuration described in the OpenApiManagementConfig class:

Hocon YAML

openapi {
    management {
        file = [ "my-openapi-1.yaml", "my-openapi-2.yaml" ] //(1)!
        enabled = false  //(2)!
        endpoint = "/openapi" //(3)!
        swaggerui {
            enabled = false //(4)!
            endpoint = "/swagger-ui" //(5)!
        }
        rapidoc {
            enabled = false //(6)!
            endpoint = "/rapidoc" //(7)!
        }
    }
}

Relative path to OpenAPI files in the resources directory, either a single file or multiple files can be specified
The on/off switch of the controller that gives the OpenAPI
Path where OpenAPI will be available
1. If a single OpenAPI file is specified, then represent entire path where file is available
2. If multiple OpenAPI files are specified, is a path prefix to the file name /openapi/{fileName}, taking the specified path and appending the file name to it without the directories and its extension, example of the file someDirectory/my-openapi-1.yaml the file path will be /openapi/my-openapi-1.
On/Off of the controller that gives SwaggerUI
Path where the SwaggerUI will be accessed
On/Off of the controller that gives Rapidoc
Path where Rapidoc will be available

openapi:
  management:
        file = [ "my-openapi-1.yaml", "my-openapi-2.yaml" ] #(1)!
    enabled: false  #(2)!
    endpoint: "/openapi" #(3)!
    swaggerui:
      enabled: false #(4)!
      endpoint: "/swagger-ui" #(5)!
    rapidoc:
      enabled: false #(6)!
      endpoint: "/rapidoc" #(7)!

Relative path to OpenAPI files in the resources directory, either a single file or multiple files can be specified
The on/off switch of the controller that gives the OpenAPI
Path where OpenAPI will be available
1. If a single OpenAPI file is specified, then represent entire path where file is available
2. If multiple OpenAPI files are specified, is a path prefix to the file name /openapi/{fileName}, taking the specified path and appending the file name to it without the directories and its extension, example of the file someDirectory/my-openapi-1.yaml the file path will be /openapi/my-openapi-1.
On/Off of the controller that gives SwaggerUI
Path where the SwaggerUI will be accessed
On/Off of the controller that gives Rapidoc
Path where Rapidoc will be available

Recommendations¶

Tip

We recommend using contract first approach and generate code using this contract, in this approach same contract file is displayed.

In the case where the code is first and the contract file is supposed to be created from it, you can use the Swagger Gradle Plugin. together with Swagger annotation set, which will be used to create the contract file.