概要
RESTfulAPIを実装する機会ができ、その際にAPIの仕様をコードで管理したく、よく聞くSwaggerについて調べたのでそのまとめです。
Swagger について
SwaggerはSmarter Bear社が開発するRESTful APIを構築するためのオープンソースフレームワークです。
RESTful APIのインターフェースを表現するための標準フォーマットがSwaggerです。
Version Preffixがついている場合はこのフォーマットを指します。
Smarter Bear社は同時に、Swaggerの標準フォーマットに則ったドキュメントと、そのドキュメントを記述するエディタと、ドキュメントからHTMLや実装の雛形を生成するツールをSwagger Toolsとして開発しています。
| Tool | description |
|---|---|
| Swagger Spec | Swaggerの標準フォーマットに則ったドキュメント(JSON/YAML) |
| Swagger Editor | Swagger Specを記述するためのエディタ |
| Swagger UI | Swagger SpecからHTMLを自動生成するツール |
| Swagger Codegen | Swagger Specから実装の雛形を自動生成するツール |
| Swagger Hub | Swagger UIのホスティングサービス |
Open API Specification 3.0 について
Swaggerは2017年に、Smarter Bear社からOpen API Initiativeに寄贈されて、名称がOpen API Specificationに変更になりました。
これまで標準仕様を指す時はVersion Preffixを付けてSwagger2.0と表現されることが多かったですが、バージョン3.0からはOpen API Specification 3.0 (OAS3.0)と表現されます。
ややこしいですが、寄贈されたのはあくまで標準仕様だけで、Swagger Tool群はSmarter Bear社が引き続き開発を継続しているので、こちらの名称はOpen API Specification Specみたいなことにはならず、Swagger Specのままです。
Swagger Spec 記法について
root階層の項目
openapi
セマンティックなVersionを指定します。2.0まではswaggerでした。
security
認証がある場合はここに記述します。公式ドキュメント
info
API全体の情報について記載します。
servers
接続先情報です。
paths
APIのURL情報について記載します。パラメーターやレスポンスはcomponentに用意し、"#/components/parameters/***"や"#/components/schemas/***"等の形で指定。
components
parameters, schemas, responsesの３項目が基本。APIサーバーのリクエストパラメータはparameters、レスポンスJSON/XMLはschemas、サーバーエラー等の共通レスポンスはresponsesに定義します。
componentにパラメータやレスポンスなどの情報をモデル化してまとめて記載することで、再利用可能で、Swagger Spec全体の見通しもよくなります。
まとめ
公式ドキュメントのパラメータの基本情報とExampleの指定については、SwaggerSpecを記載していく上でかなり助けになりました。
リポジトリでファイル管理できて、コマンド一つで仕様書として吐き出せるのでSwagger、便利です。