Swaggerフレームワークは、APIの言語に依存しない、人間が読める形式を定義するのに役立ち、実装を容易にし、採用を促進し、開発を安定させます。
APIのSwagger仕様を生成するには、一般的に2つのプロセスが用いられます。
- 実行時におけるSwaggerの生成: この方法では、様々なリソース、メソッド、コントローラーに追加されたメタデータに基づいて、APIからSwaggerコントラクトが生成されます。このメタデータは、実行時にSwaggerコントラクト、クライアントサイドコード、およびその他のアーティファクトを生成します。通常、このメタデータはコードアノテーションの形式で記述されます。ツールは、様々なメソッドと関数がそのリソースに対して呼び出されると起動し、APIで定義されたメタデータからSwaggerコントラクトを生成します。
- ビルド時におけるSwaggerの生成: この方法では、APIを前処理する際、つまり実行前にSwaggerコントラクトが生成されます。API内の様々なリソース、メソッド、関数に対するコメントがSwagger仕様の生成に役立ちます。これらのコメントは通常、コントラクトを生成するために使用するツールの種類に基づいて、事前に定義された特殊な構文で記述されます。ツールは、これらの特殊なコメントについてAPIコードをスキャンし、出力としてSwaggerコントラクトを生成します。
どちらの方法にも長所と短所があります。実行時にSwagger仕様を生成すると、コードからより正確なAPIコントラクトが生成されますが、追加の依存関係、開発時間、およびシステムへのオーバーヘッドの形でソフトウェアの負荷がかかります。逆に、APIの実行前にSwaggerコントラクトを生成する方が軽量なプロセスですが、手動で維持する必要があるため、生成されたSwaggerコントラクトがAPIを正確に記述していない可能性が高くなります。
SwaggerHubチームは最近、無料のリソースである「*Swaggerで既存のAPIをドキュメント化する*」を公開し、APIのSwaggerを生成するこれら2つのアプローチを検討しました。
学習内容:
- APIドキュメントの重要性
- ドキュメントにSwaggerを使用する理由
- APIにSwaggerを追加するアプローチ
- Swagger仕様のドキュメント化
コピーをゲット！