Swagger とは

Swagger を使用すると、API の構造を記述して機械が読み取れるようにすることができます。API が自身の構造を記述できる能力は、Swagger のすべての素晴らしさの根源です。なぜそれがそれほど素晴らしいのでしょうか？API の構造を読み取ることで、美しくインタラクティブな API ドキュメントを自動的に作成できます。また、多くの言語で API のクライアントライブラリを自動的に生成したり、自動テストのような他の可能性を探ったりすることもできます。Swagger は、API に、API 全体の詳細な記述を含む YAML または JSON を返すように要求することで、これを行います。このファイルは、基本的に OpenAPI Specification に準拠する API のリソースリストです。この仕様では、次のような情報を含めるように要求されます。

API がサポートするすべての操作は何ですか？
API のパラメータと、それが返すものは何ですか？
API に何らかの認証が必要ですか？
そして、利用規約、連絡先情報、API の使用ライセンスのような楽しいことまで。

API の Swagger 仕様は手動で記述することも、ソースコードのアノテーションから自動的に生成することもできます。コードから Swagger を生成できるツールのリストについては、swagger.io/open-source-integrations を確認してください。

API の Swagger 仕様を作成しました。さて、次は何をすればいいですか？

Swagger が API 開発をさらに推進するのに役立つ方法はいくつかあります。

デザインファーストのユーザー: Swagger Codegen を使用して、API のサーバスタブを生成します。残っているのはサーバロジックの実装だけで、API はすぐに公開できます！
Swagger Codegen を使用して、40 以上の言語で API のクライアントライブラリを生成します。
Swagger UI を使用して、ユーザーがブラウザで直接 API 呼び出しを試すことができるインタラクティブな API ドキュメントを生成します。
仕様を使用して、API 関連ツールを API に接続します。たとえば、仕様を SoapUI にインポートして、API の自動テストを作成します。
他にもたくさんあります！Swagger と統合されているオープンソースツールと商用ツールをチェックしてください。