Zenn
🍎

Spring Boot + KotlinプロジェクトのソースコードからSwagger UIやYAMLを生成する

2023/01/14に公開
Gradle
Kotlin
Spring Boot
Swagger
OpenAPI
tech

背景

Spring Boot + Kotlinプロジェクトのソースコードをもとに、Swagger UIやOpenAPIのYAML定義ファイルを出力したい。

Springdoc-openapi vs SpringFox

以下の理由から、SpringFoxは選択肢から外した。

一方でSpringdoc-openapiはアクティブにメンテナンスされており、ドキュメントも充実していて良い感じのようにみえる。

手順

ためした環境:

  • Spring Boot 2.7.7
  • Kotlin 1.6.21
  • JDK 11
  • Gradle 7.6

Swagger UI

build.gradle.ktsに追加。

implementation("org.springdoc:springdoc-openapi-ui:1.6.13")

こんな感じの異様にシンプルなコントローラーに適当にアノテーションをつける。

@RestController
@RequestMapping("/v1")
class OrdersController(
    private val service: MyService
) {
    @GetMapping("/{orderId}/orders")
    @Operation(summary = "エンドポイントの説明です")
    fun orders(
        @PathVariable orderId: String,
        @RequestParam("fields") @Parameter(description = "パラメータfieldsの説明です", required = true) fields: String?,
        @RequestParam("limit") @Parameter(description = "パラメータlimitの説明です", required = false) limit: Int?,
    ): ResponseEntity<String> {
        val result = service.fetch(fields, limit)
        return ResponseEntity.ok(result)
    }
}

起動して http://localhost:8080/swagger-ui/index.html にアクセスするとSwagger UIが出る。

YAMLがほしい場合は、 http://localhost:8080/v3/api-docs.yaml にアクセスする。

openapi: 3.0.1
info:
  title: OpenAPI definition
  version: v0
servers:
- url: http://localhost:8080
  description: Generated server url
paths:
  /v1/{orderId}/orders:
    get:
      tags:
      - orders-controller
      summary: エンドポイントの説明です
      operationId: orders
      parameters:
      - name: orderId
        in: path
        required: true
        schema:
          type: string
      - name: fields
        in: query
        description: パラメータfieldsの説明です
        required: true
        schema:
          type: string
      - name: limit
        in: query
        description: パラメータlimitの説明です
        required: false
        schema:
          type: integer
          format: int32
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                type: string
components: {}

なお、http://localhost:8080/v3/api-docs からはJSONがもらえる。

コマンドラインでYAML生成

しかし人生においてはコマンドラインからYAMLを生成したい場合もあるものだ。

build.gradle.ktsに追加する。

plugins {
        ...
	id("org.springdoc.openapi-gradle-plugin") version "1.5.0"
	...
}


openApi {
	outputFileName.set("openapi.yml")
	outputDir.set(file("./"))
	apiDocsUrl.set("http://localhost:8080/v3/api-docs.yaml")
}

以下のコマンドでカレントにopenapi.ymlが出力される。

./gradlew generateOpenApiDocs

なおJSONがほしい場合はこの設定を使う。

openApi {
	outputFileName.set("openapi.json")
	outputDir.set(file("./"))
	apiDocsUrl.set("http://localhost:8080/v3/api-docs")
}

さらなるアノテーション

ソースコードに書いていくアノテーションについては、Springdoc-openapiや、swagger-core
の各ドキュメントを参照すると良いだろう。

Discussion