OpenAPIを使ったKotlinとSpring Bootのデータモデルの作り方

Kotlin

はじめに

KotlinとSpring Bootを使用した開発を効率化するために、OpenAPIを活用してデータモデルを自動生成する方法について解説します。

公式ドキュメント

OpenAPIやSpring Boot、Gradleに関する詳細な情報は、公式ドキュメントを参照してください。以下に主要なドキュメントのリンクを示します。

  • OpenAPIの公式ドキュメント
OpenAPI Specification v3.1.0 | Introduction, Definitions, & More
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs.
spec.openapis.org
  • OpenAPI GeneratorのKotlin Spring用設定オプション
Documentation for the kotlin-spring Generator | OpenAPI Generator
METADATA
openapi-generator.tech
  • OpenAPI GeneratorのGitHubリポジトリ
GitHub - OpenAPITools/openapi-generator: OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)
OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configurat...
github.com
  • Spring Bootの公式ドキュメント
Spring Boot :: Spring Boot
docs.spring.io
  • Gradleの公式ドキュメント
Gradle User Manual
docs.gradle.org

環境構築

KotlinとSpring BootのプロジェクトにOpenAPIを導入するための手順については、以前書いた以下の記事を参考にしてください。

  • KotlinとSpring BootでのOpenAPIを使用できるようにする(環境構築)
KotlinとSpring BootでのOpenAPIを使用できるようにする(環境構築)
はじめに OpenAPIを使用してKotlinとSpring Bootでコードを自動生成し、開発の効率化を図る方法を紹介します。これにより、手動でのコード記述の手間を減らし、一貫性のある高品質なコードを効率的に生成することができます。 準備...
techchallengediaryth.com
2024.07.15

OpenAPIのYAMLに記述方法について

YAMLの基本構造

OpenAPIのYAMLファイルでは、APIの仕様を階層的に記述します。以下に、主要なポイントを示します。

  • キー(Key)と値(Value)のペアがノードを構成します。
  • 各階層はレベル(Level)で表現されます。
    1. 第一階層 (Level 1): YAMLファイルの最上位に位置する要素。これをルートノードと呼びます。例: openapi, info, paths, components
    2. 第二階層 (Level 2): 第一階層の要素に含まれる子要素。これを子ノード (Child Node) と呼びます。例: info の中の title や version、components の中の schemas
    3. 第三階層 (Level 3): 第二階層の要素に含まれるさらに下位の要素。例: schemas の名前 (Greeting など)
    4. 第四階層 (Level 4): 第三階層の要素に含まれる要素。例: スキーマのプロパティ (Greeting の中の type, properties など)

OpenAPIの基本オブジェクトについて

OpenAPIの基本的なオブジェクトについていくつか紹介します。

  • OpenAPI Object
    このオブジェクトはAPI仕様書全体のルートノードで、OpenAPIのバージョンのや他の主要なオブジェクト（Info Object、Paths Object、Components Objectなど）を含みます。

    1. ルートノード
    2. Info Object
    3. Paths Object
    4. Components Object
    5. etc

  • Info Object
    このオブジェクトはAPIに関する基本的な情報を提供し、ユーザーがAPIの目的や使用方法を理解するのに役立ちます。

    1. 第二階層
    2. APIのタイトル
    3. APIのバージョン
    4. APIの説明
    5. etc

  • Components Object
    このオブジェクトはAPI内で使用される再利用可能な要素を定義します。データモデルや共通のレスポンス、パラメータ、認証スキームなどが含まれます。

    1. 第二階層
    2. データモデル
    3. 標準の応答メッセージ
    4. 共通のパラメータ
    5. etc

  • Paths Object
    このオブジェクトは、APIが提供するすべてのエンドポイントと、それらのエンドポイントで利用可能な操作を定義します。

    1. 第二階層
    2. HTTPメソッド（GET, POST, PUT, DELETEなど）
    3. エンドポイントごとのパラメータとレスポンス

データモデルのYAMLのサンプル

以下のYAMLのサンプルは、OpenAPI仕様を使用してデータモデルを定義する方法を示しています。

openapi: 3.1.0
info:
  title: Sample API
  version: 1.0.0
components:
  schemas:
    SampleModel:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: "ID"
        name:
          type: string
          description: "名前"
  • openapi: OpenAPIのバージョン
  • info: Info Object
    • title: APIの名前
    • version: APIのバージョン
  • components: Components Object
    • schemas
      • SampleModel>: データモデルの名前
        • type: データモデルの型
        • properties: データモデルのプロパティ
          • id: プロパティの名前
            • type: プロパティのデータ型
            • format: データのフォーマット
            • description: プロパティの説明
          • name: プロパティの名前
            • type: プロパティのデータ型
            • description: プロパティの説明

動作確認

以下のコマンドを実行します。

./gradlew openApiGenerate

このコマンドを実行すると、OpenAPIの仕様に基づいて以下のモデルが自動生成されます。

package com.app.model

import java.util.Objects
import com.fasterxml.jackson.annotation.JsonProperty
import javax.validation.constraints.DecimalMax
import javax.validation.constraints.DecimalMin
import javax.validation.constraints.Email
import javax.validation.constraints.Max
import javax.validation.constraints.Min
import javax.validation.constraints.NotNull
import javax.validation.constraints.Pattern
import javax.validation.constraints.Size
import javax.validation.Valid
import io.swagger.v3.oas.annotations.media.Schema

/**
 * 
 * @param id ID
 * @param name 名前
 */
data class SampleModel(

    @Schema(example = "null", description = "ID")
    @get:JsonProperty("id") val id: kotlin.Long? = null,

    @Schema(example = "null", description = "名前")
    @get:JsonProperty("name") val name: kotlin.String? = null
) {

}

file

以上がOpenAPIを使用したデーモデルを生成するプロセスになります。

コメント

タイトルとURLをコピーしました