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.yaml" //(1)!
        enabled = false  //(2)!
        endpoint = "/openapi" //(3)!
        swaggerui {
            enabled = false //(4)!
            endpoint = "/swagger-ui" //(5)!
        }
        rapidoc {
            enabled = false //(6)!
            endpoint = "/rapidoc" //(7)!
        }
    }
}

1. Relative path to the OpenAPI file in the resources directory
2. The on/off switch of the controller that gives the OpenAPI
3. The path where the OpenAPI will be accessed
4. On/Off of the controller that gives SwaggerUI
5. The path where the SwaggerUI will be accessed
6. On/Off of the controller that gives Rapidoc
7. Path where Rapidoc will be available

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

1. Relative path to the OpenAPI file in the resources directory
2. The on/off switch of the controller that gives the OpenAPI
3. The path where the OpenAPI will be accessed
4. On/Off of the controller that gives SwaggerUI
5. The path where the SwaggerUI will be accessed
6. On/Off of the controller that gives Rapidoc
7. 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.