Swagger Codegen（コード生成）

Swagger は、OpenAPI 仕様（以前は Swagger 仕様と呼ばれていました）を中心に構築されたオープンソースツール群であり、RESTful Web サービスの設計、構築、文書化、および利用に使用されます。

Swagger の主な構成要素は次のとおりです:

  • Swagger Editor: ブラウザベースのエディタで、OpenAPI 仕様を記述できます。
  • Swagger UI: ビジュアルな API ドキュメントインターフェースで、開発者が対話的に API を探索できます。
  • Swagger Codegen: OpenAPI 仕様に基づいてクライアントコードとサーバースタブを自動生成します。

OpenAPI 仕様は、RESTful API を記述するための言語に依存しない定義形式です。

OpenAPI を使用すると、ソースコードや追加のドキュメントにアクセスすることなく、人間とコンピュータがサービスの機能を発見および理解できます。

Swagger Codegen（コード生成）

環境準備

開始する前に、システムに以下がインストールされていることを確認してください:

  • Java 8+
  • Maven（Javaプロジェクト用）
  • Git（ソースコードの取得用）

Swagger Codegen のインストール:

# 方法1: 使用homebrew (macOS)
brew install swagger-codegen

# 方法2: 从GitHub下载JAR文件
wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.36/swagger-codegen-cli-3.0.36.jar -O swagger-codegen-cli.jar
java -jar swagger-codegen-cli.jar help

クライアントSDKの生成

Java クライアントの生成

Petstore API を例に Java クライアントを生成する:

# 使用命令行工具
swagger-codegen generate -i https://petstore.swagger.io/v2/swagger.json -l java -o ./java-client

# 或使用JAR文件
java -jar swagger-codegen-cli.jar generate \
  -i https://petstore.swagger.io/v2/swagger.json \
  -l java \
  -o ./java-client

生成されたクライアントSDKの構造:

java-client/
├── pom.xml                  # Maven项目文件
├── README.md                # 说明文档
├── src/
│   ├── main/
│   │   ├── java/           # 生成的Java代码
│   │   └── resources/      # 配置文件
│   └── test/               # 测试代码
└── .gitignore

生成された Java クライアントの使用:

例

import io.swagger.client.*;
import io.swagger.client.auth.*;
import io.swagger.client.model.*;
import io.swagger.client.api.PetApi;

public class Example {
    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
       
        // APIキー認証を設定
        ApiKeyAuth apiKey = (ApiKeyAuth) defaultClient.getAuthentication("api_key");
        apiKey.setApiKey("YOUR API KEY");
       
        PetApi apiInstance = new PetApi();
        try {
            Pet result = apiInstance.getPetById(789L);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling PetApi#getPetById");
            e.printStackTrace();
        }
    }
}

Python クライアントの生成

Python クライアントを生成する:

swagger-codegen generate -i https://petstore.swagger.io/v2/swagger.json -l python -o ./python-client

Python クライアントの使用例:

例

import swagger_client
from swagger_client.rest import ApiException

# APIクライアントインスタンスを作成
api_instance = swagger_client.PetApi()
api_client = api_instance.api_client

# APIキーを設定
api_client.configuration.api_key['api_key'] = 'YOUR_API_KEY'

try:
    # 指定されたIDのペットを取得
    pet = api_instance.get_pet_by_id(pet_id=789)
    print(pet)
except ApiException as e:
    print("Exception when calling PetApi->get_pet_by_id: %s\n" % e)

他の言語のサポート

Swagger Codegen は、以下を含むさまざまな言語とフレームワークをサポートしています（ただしこれらに限定されません）:

  • JavaScript/TypeScript（Node.js、Angular、Reactなど）
  • Ruby
  • PHP
  • C#/.NET
  • Go
  • Swift
  • Kotlin
  • Scala

サポートされている言語のリストを表示:

swagger-codegen langs

サーバースタブコードの生成

Spring サーバーコードの生成

Spring Boot サーバースタブを生成する:

swagger-codegen generate \
  -i https://petstore.swagger.io/v2/swagger.json \
  -l spring \
  -o ./spring-server

生成されたSpringサーバーコードの構造:

spring-server/
├── pom.xml                  # Maven项目文件
├── README.md                # 说明文档
├── src/
│   ├── main/
│   │   ├── java/           # 控制器接口和模型类
│   │   └── resources/      # 配置文件和静态资源
│   └── test/               # 测试代码
└── .gitignore

生成されたコントローラーインターフェースを実装:

例

@Controller
public class PetApiController implements PetApi {
    @Override
    public ResponseEntity<Pet> getPetById(Long petId) {
        // APIロジックを実装
        Pet pet = new Pet();
        pet.setId(petId);
        pet.setName("サンプルのペット");
        pet.setStatus(Pet.StatusEnum.AVAILABLE);
        return ResponseEntity.ok(pet);
    }
}

Node.js サーバーコードの生成

Node.js サーバーコードを生成する:

swagger-codegen generate \
  -i https://petstore.swagger.io/v2/swagger.json \
  -l nodejs-server \
  -o ./nodejs-server

Node.js サーバーの使用例:

例

// 生成されたserviceファイルでビジネスロジックを実装
module.exports.getPetById = function(petId) {
  return new Promise(function(resolve, reject) {
    var examples = {};
    examples['application/json'] = {
      "id": petId,
      "name": "サンプルのペット",
      "status": "available"
    };
    resolve(examples[Object.keys(examples)[0]]);
  });
}

OpenAPI Generator の応用

OpenAPI Generator vs Swagger Codegen

OpenAPI Generator は Swagger Codegen のフォークであり、2018年から独立して開発されています。主な利点は次のとおりです:

  • より活発なコミュニティメンテナンス
  • より広範なテンプレートサポート
  • より優れたOpenAPI 3.0サポート
  • より多くの設定オプションとカスタマイズ機能

OpenAPI Generator のインストール:

# 使用npm安装
npm install @openapitools/openapi-generator-cli -g

# 使用Homebrew安装
brew install openapi-generator

# 下载JAR文件
wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/6.0.1/openapi-generator-cli-6.0.1.jar -O openapi-generator-cli.jar

インストールと基本使用

基本的な使用方法:

# 显示帮助信息
openapi-generator help

# 生成Java客户端
openapi-generator generate \
  -i https://petstore.swagger.io/v2/swagger.json \
  -g java \
  -o ./java-client

# 列出支持的生成器
openapi-generator list

カスタムテンプレート

テンプレートの基本知識

OpenAPI Generator は Mustache テンプレートエンジンを使用します。生成コードをカスタマイズするには、以下が必要です:

  1. デフォルトテンプレートを取得
  2. ニーズに合わせてテンプレートを変更
  3. カスタムテンプレートを使用してコードを生成

カスタムテンプレートを作成<
# 使用JAR文件获取特定语言的模板
java -jar openapi-generator-cli.jar author template \
  -g java \
  -o ./custom-templates/java

テンプレートファイルの例（Java の api.mustache）:

{{>licenseInfo}}
package {{package}};

{{#imports}}import {{import}};
{{/imports}}

{{#operations}}
public interface {{classname}} {
    {{#operation}}
    {{#summary}}
    /**
     * {{summary}}
     * {{/summary}}
     {{#notes}}
     * {{notes}}
     {{/notes}}
     */
    {{#returnType}}{{returnType}} {{/returnType}}{{^returnType}}void {{/returnType}}{{operationId}}({{#allParams}}{{dataType}} {{paramName}}{{^-last}}, {{/-last}}{{/allParams}});
    
    {{/operation}}
}
{{/operations}}

テンプレートを適用してコードを生成

カスタムテンプレートを使用してコードを生成する:

openapi-generator generate \
  -i https://petstore.swagger.io/v2/swagger.json \
  -g java \
  -o ./java-client-custom \
  -t ./custom-templates/java

カスタム設定

グローバル設定オプション

OpenAPI Generator は複数のグローバル設定オプションをサポートしています:

openapi-generator generate \
  -i spec.yaml \
  -g java \
  -o output \
  --api-package com.example.api \
  --model-package com.example.model \
  --package-name com.example \
  --git-repo-id my-repo \
  --git-user-id my-username

言語固有の設定

生成器ごとに固有の設定オプションがあります:

# Java客户端生成器的特定选项
openapi-generator generate \
  -i spec.yaml \
  -g java \
  -o output \
  --library retrofit2 \
  --java8 true \
  --use-rx-java true

設定ファイルの使用

よく使う設定を保存する設定ファイルを作成できます:

config.json ファイル

{
  "artifactId": "petstore-client",
  "groupId": "com.example",
  "library": "retrofit2",
  "apiPackage": "com.example.api",
  "modelPackage": "com.example.model",
  "invokerPackage": "com.example.client",
  "dateLibrary": "java8",
  "java8": true
}

設定ファイルを使用する:

openapi-generator generate \
  -i spec.yaml \
  -g java \
  -o output \
  -c config.json

実践プロジェクト事例

ゼロから始めるAPI設計

Swagger Editor を使用して API を設計する:

  1. アクセスhttps://editor.swagger.io/
  2. OpenAPI 仕様ファイルを作成する:

例

openapi: 3.0.0
info:
  title:製品管理API
  version: 1.0.0
  description:製品を管理するためのRESTful API
servers:
  - url: https://api.example.com/v1
paths:
  /products:
    get:
      summary:製品リストの取得
      responses:
        '200':
          description:成功
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'
    post:
      summary:新製品の作成
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductInput'
      responses:
        '201':
          description:作成成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
  /products/{productId}:
    get:
      summary:単一製品の取得
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description:成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
components:
  schemas:
    Product:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        price:
          type: number
        category:
          type: string
        createdAt:
          type: string
          format: date-time
    ProductInput:
      type: object
      required:
        - name
        - price
      properties:
        name:
          type: string
        price:
          type: number
        category:
          type: string

完全なプロジェクトコード生成

設計したAPI仕様から完全なプロジェクトを生成する:

  1. API 仕様を保存:product-api.yaml
  2. フロントエンドとバックエンドのコードを生成する:
# 生成Spring Boot服务端
openapi-generator generate \
  -i product-api.yaml \
  -g spring \
  -o ./product-service \
  --additional-properties=java8=true,dateLibrary=java8

# 生成React前端
openapi-generator generate \
  -i product-api.yaml \
  -g typescript-fetch \
  -o ./product-frontend \
  --additional-properties=supportsES6=true,npmName=product-api-client

よくある問題と解決方法

  1. 生成されたコードがコンパイルできない

    • OpenAPI仕様が標準に準拠していることを確認する
    • カスタムテンプレートの構文エラーを確認する
    • ジェネレーターを最新版に更新する

  2. カスタムテンプレートが反映されない

    • テンプレートのパスが正しいことを確認する
    • テンプレートのファイル名が元のテンプレートと一致しているか確認する
    • 相対パスではなく絶対パスを使用する

  3. 生成されたコードに特定の機能が欠けている

    • OpenAPI仕様が必要な機能を完全に定義しているか確認する
    • 正しいジェネレーターと設定オプションを使用しているか確認する
    • カスタムテンプレートを使用して追加機能を追加することを検討する

  4. 生成されたコードが既存のプロジェクトと互換性がない

    • 設定オプションを使用してパッケージ名と命名規則を調整する
    • カスタムテンプレートでコードスタイルを調整する
    • APIインターフェースのみを生成し、具体的なロジックは手動で実装することを検討する

高度な機能とベストプラクティス

バージョン管理

API バージョン管理のベストプラクティス:

  1. OpenAPI仕様でバージョン番号を明確にする
  2. セマンティックバージョニング（SemVer）を使用する
  3. APIのバージョンごとに異なるベースパスを使用する
  4. すべてのバージョンの仕様ファイルを保存する

CI/CD 統合

コード生成を CI/CD パイプラインに統合する:

例

# GitHub Actionsワークフローの例
name: Generate API Client

on:
  push:
    paths:
      - 'api-specs/**'

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
     
      - name: Set up JDK
        uses: actions/setup-java@v2
        with:
          java-version: '11'
         
      - name: Install OpenAPI Generator
        run: npm install @openapitools/openapi-generator-cli -g
       
      - name: Generate Client
        run: |
          openapi-generator generate \
            -i api-specs/product-api.yaml \
            -g typescript-fetch \
            -o ./generated-client
           
      - name: Commit and Push
        run: |
          git config --global user.name 'GitHub Actions'
          git config --global user.email '[email protected]'
          git add ./generated-client
          git commit -m "Auto-generate API client"
          git push

エンタープライズ向けアプリケーションの提案

エンタープライズプロジェクトの場合:

  1. API仕様を一元管理する

    • API仕様を専用のGitリポジトリで管理する
    • 品質を確保するためにコードレビュープロセスを実施する

  2. 生成コードのスタイルガイドを確立する

    • 一貫した命名規則を作成する
    • エラーハンドリングの標準を策定する
    • 統一された認証処理方法を設計する

  3. 生成コードと手書きコードを併用する

    • 基本フレームワークとデータモデルを生成する
    • 複雑なビジネスロジックは手動で実装する
    • アダプターパターンを使用して生成コードと手書きコードを分離する

  4. マイクロサービスアーキテクチャを検討する

    • 各マイクロサービスごとに独立したAPI仕様を維持する
    • APIゲートウェイを使用して外部インターフェースを統一する
    • コード生成によりサービス間のクライアントを実現する
その他の拡張機能