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" ] Relative path to OpenAPI files in the resources directory, either a single file or multiple files can be specified

        enabled = false  The on/off switch of the controller that gives the OpenAPI

        endpoint = "/openapi" Path where OpenAPI will be available
If a single OpenAPI file is specified, then represent entire path where file is available
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.


        swaggerui {
            enabled = false On/Off of the controller that gives SwaggerUI

            endpoint = "/swagger-ui" Path where the SwaggerUI will be accessed

        }
        rapidoc {
            enabled = false On/Off of the controller that gives Rapidoc

            endpoint = "/rapidoc" Path where Rapidoc will be available

        }
    }
}

openapi:
  management:
        file = [ "my-openapi-1.yaml", "my-openapi-2.yaml" ] Relative path to OpenAPI files in the resources directory, either a single file or multiple files can be specified

    enabled: false  The on/off switch of the controller that gives the OpenAPI

    endpoint: "/openapi" Path where OpenAPI will be available
If a single OpenAPI file is specified, then represent entire path where file is available
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.


    swaggerui:
      enabled: false On/Off of the controller that gives SwaggerUI

      endpoint: "/swagger-ui" Path where the SwaggerUI will be accessed

    rapidoc:
      enabled: false On/Off of the controller that gives Rapidoc

      endpoint: "/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.