Swagger for API ドキュメント

Swagger は、開発者が RESTful API を設計、構築、文書化、使用するのに役立つオープンソース ソフトウェア フレームワークです。Swagger ドキュメントは、Swagger 仕様を使用して作成された RESTful API を表現したものです。Swagger 仕様は、REST API の標準インターフェイス記述言語です。これにより、開発者は API の構造を記述し、人間が読める形式でドキュメントを生成できます。生成された Swagger ドキュメントには、API エンドポイント、リクエストおよびレスポンスのパラメーター、その他の関連詳細に関する情報が含まれています。他の開発者はこれを使用して、API の機能を理解し、API を呼び出すことができます。

Swagger の機能

Swagger のドキュメントでは、次のような多くの機能が提供されています。

1. インタラクティブなドキュメント: 開発者が API 呼び出しを試し、ブラウザベースの UI で応答を確認できるようにします。
2. API 定義: API の動作、そのエンドポイント、パラメーター、および予期される応答について、明確かつ簡潔で人に優しい定義を提供します。
3. コード生成: 複数のプログラミング言語でサーバーとクライアントのコードを生成し、開発プロセスのスピードアップに役立ちます。
4. 検証: API リクエストと応答を自動的に検証し、API の仕様を満たしていることを確認します。
5. ドキュメントの生成: HTML、JSON、YAML などのさまざまな形式で API ドキュメントを自動的に生成します。
6. コラボレーション: API ドキュメントの一元的な場所を提供することで、API 作成者、開発者、関係者間のコラボレーションをサポートします。
7. テスト: API 呼び出しをテストし、それらが望ましい動作を満たしていることを確認するための環境を提供します。
8. バージョニング: API のバージョン管理をサポートし、ユーザーが API の複数のバージョンを表示して操作できるようにします。

Swagger ドキュメントでは、次のようないくつかのプログラミング言語がサポートされています。

1. ジャワ
2. Node.js
3. PHP
4. パイソン
5. ルビー
6. 行く
7. C#
8. スカラ座
9. パール

Spring Boot で Swagger を有効にする

Spring Boot アプリケーションで Swagger ドキュメントを有効にするには、次の手順に従う必要があります。

1. springfox-swagger2 および springfox-swagger-ui の依存関係をプロジェクトに追加します。
2. 構成クラスに @EnableSwagger2 アノテーションを付けて、Spring Boot アプリケーションで Swagger サポートを有効にします。
3. Docket Bean を作成して、API バージョン、タイトル、説明などの Swagger プロパティを設定します。
4. RESTful API に @Api、@ApiOperation、@ApiParam などの適切な Swagger アノテーションを付けます。
5. Spring Boot アプリケーションを実行し、次の URL にある Swagger UI にアクセスします。http://localhost:port/swagger-ui.htmlここで、 port はアプリケーションが実行されている HTTP ポートです。

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

Spring REST API を使用した Swagger 2 のセットアップ | ベルドゥン

OpenAPI 3.0 を使用した Spring REST API の文書化 | ベルドゥン