Designing APIs with Swagger and OpenAPI
目次
- 目次
- はじめに
- Open APIの特徴
- 1. YAMLやJSONなどのテキストファイルで仕様を記述できる。
- 2. OpenAPIの仕様データから、仕様書を自動生成できる。
- 3. OpenAPIの仕様データから、APIのクライアントやサーバのコードを自動生成できる
- Open APIの仕様の書き方
- シングルHTMLファイルのAPIドキュメントを生成する
- 参考資料
- MyEnigma Supporters
はじめに
REST APIは、ソフトウェアのAPIの基本だと思いますが、
そのドキュメントの書き方は結構悩ましいと思います。
仕様変更すると、すぐにドキュメントとソースコードの乖離が発生しますし、
ソースコードとドキュメントを同じgit リポジトリで管理しようと思っても、
仕様書としてよく使われるWordやExcelはバイナリファイルなので、
バージョン管理がしずらいです。
そこで、テキストファイルであるyamlやjsonファイルを使って
REST APIの仕様を記述する標準があります。
それが、OpenAPIです。
Home - OpenAPI Initiative
madogiwa0124.hatenablog.com
以前はSwaggerというOSSのプロジェクトが使っていた仕様なので、
Swaggerと呼ばれることもあります。
本記事では、このOpen APIによるREST APIの仕様書作成の
特徴と仕様書作成方法などをまとめておきたいと思います。
続きを読む