MicronautでOpenAPIを使う方法

以下の環境で作成

• Micronaut: 2.1.3
• Kotlin: 1.4.10

準備

以下の2つをbuild.gradleに追加する。

kapt("io.micronaut.openapi:micronaut-openapi")
implementation("io.swagger.core.v3:swagger-annotations")

OpenAPIドキュメントの生成

Application.ktとかに以下を追記する。

@OpenAPIDefinition(
    info = Info(
        title = "Hello world",
        version = "0.0"
    )
)
object Api {
}

ここでビルドすると build/tmp/kapt3/classes/main/META-INF/swagger に以下のようなOpenAPIドキュメントが生成される。

openapi: 3.0.1
info:
  title: Hello world
  version: "0.0"

エンドポイントを増やしてみる

適当なコントローラを作りエンドポイントを増やしてみる。

@Controller("/test")
class TestController {
    @Get
    fun get(): Person = Person("太郎", "浦島", 10)

    @Post
    fun post(@Body person: Person): Person = person
}

data class Person(
    val firstName: String,
    val lastName: String,
    val age: Int
)

ビルドすると以下のようなOpenAPIドキュメントが生成される。

openapi: 3.0.1
info:
  title: Hello world
  version: "0.0"
paths:
  /test:
    get:
      operationId: get
      parameters: []
      responses:
        default:
          description: get default response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
    post:
      operationId: post
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Person'
        required: true
      responses:
        default:
          description: post default response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
components:
  schemas:
    Person:
      required:
      - firstName
      - lastName
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        age:
          type: integer
          format: int32

Swagger UI

Swagger UIで確認する方法も用意されている。

プロジェクトルートに以下の内容で openapi.properties を作成する。

swagger-ui.enabled=true

application.ymlに以下を追記する。

micronaut:
  router:
    static-resources:
      swagger:
        paths: classpath:META-INF/swagger
        mapping: /swagger/**
      swagger-ui:
        paths: classpath:META-INF/swagger/views/swagger-ui
        mapping: /swagger-ui/**

アプリケーションを起動して http://localhost:8080/swagger-ui にアクセスするとSwagger UIで確認ができる。

ReDoc, RapiDoc

ReDoc, RapiDocでも確認することが可能。

openapi.properties に以下を追記する。

redoc.enabled=true
rapidoc.enabled=true

application.yml に以下を追記する。

micronaut:
  router:
    static-resources:
      redoc:
        paths: classpath:META-INF/swagger/views/redoc
        mapping: /redoc/**
      rapidoc:
        paths: classpath:META-INF/swagger/views/rapidoc
        mapping: /rapidoc/**

• ReDoc

http://localhost:8080/redoc

• RapiDoc

http://localhost:8080/rapidoc