Swagger Tools で API 設計およびドキュメントを生成します。
今回は、OpenAPI 3.0 で定義してみます。
Contents
OpenAPI/Swagger
OpenAPI(Swagger) は API を記述する為の仕様です。
Swagger Specification は Linux Foundation に寄贈され、現在では OpenAPI Specification となり、OpenAPI Initiative によりプロジェクトが進められています。
Swagger 3.0 で構造もシンプルになり、より汎用性が高くなっています。
OpenAPI Initiative は Microsoft、Google、IBM、CapitalOne SmartBearなどの30以上の組織から結成されています。
SmartBear Software は Swagger の開発元であった Reverb Technologies を買収し、現在も Swagger Tooles を開発している企業です。
OpenAPI仕様
YAMLファイルで記述する際の、OpenAPI Object をみていきます。
- openapi (必須)
OpenAPI仕様バージョン - info (必須)
APIに関するメタデータを表すオブジェクト - servers
ターゲットサーバーへの接続情報を表すオブジェクト - paths (必須)
APIで使用可能なパスと操作を表すオブジェクト
個々のエンドポイントとその操作への相対パス - components
仕様のさまざまなスキーマを表すオブジェクト - security
API全体で使用できるセキュリティメカニズムを表すオブジェクト - tags
追加のメタデータとともに仕様で使用されるタグを表すオブジェクト - externalDocs
追加の外部ドキュメントを表すオブジェクト
こちらを記述する為の便利なツール(Swagger Editor)がありますので、そちらを使用してみます。
Swagger Tools
クラウド上で操作できる 統合環境の SwaggerHub もありますが、今回は Docker で構築してみます。
Swagger UI
Swagger UI はドキュメント化するツールです。
OpenAPI Specification 準拠の API からドキュメントを動的に生成できます。
インストール
-
docker でインストール
12docker pull swaggerapi/swagger-uidocker run -d -p 80:8080 swaggerapi/swagger-ui
Swagger Editor
OpenAPI を記述できるオンラインエディタです。
ブラウザー内で YAML の OpenAPI 仕様を編集し、Swagger UI でドキュメントをリアルタイムでプレビューできます。
画面は、左側にエディター、右側に Swagger UI となっています。
インストール
-
docker でインストール
12docker pull swaggerapi/swagger-editordocker run -d -p 80:8080 swaggerapi/swagger-editor -
80番ポートを使用したくない場合 & name 指定
12docker pull swaggerapi/swagger-editordocker run -d -p 8888:80800 --name swagger-editor -it swaggerapi/swagger-editor -
Docker Hub
https://hub.docker.com/r/swaggerapi/swagger-editor
使い方
メニューには大きく、下記があります。
- File
インポートやエクスポートが行えます。 - Edit
フォーマットのコンバート用のメニューです。 - Insert
追加したい項目を入力フォームからエディタに挿入できます。 - Generate Server
指定した言語でスタブサーバー用のソースをダウンロードできます。 - Generate Client
指定した言語でクライアント用のソースをダウンロードできます。
File、Edit、Insert をさらにみていきます。
File
File メニューをみていきます。
- Import URL
OpenAPI に準拠したフォーマットの URL からインポートできます。 - Import file
OpenAPI に準拠したファイルからインポートできます。 - Save as YAML
YAML ファイルで保存します。 - Convert and save as JSON
JSON ファイルにコンバートして保存します。 - Clear editor
読み込んでいるエディタをクリアします。
Edit
Edit メニューをみていきます。
- Convert to YAML
YAML にコンバートします。 - Convert to OpenAPI 3
Swagger 2.0 で記述視されている旧仕様から OpenAPI 3 の仕様にコンバートします。
Insert
Insert メニューをみていきます。
- Add Path Item
Path の追加
summary と description も一緒に追加できます。 - Add Operation
Path の Operation を追加
記述している Path と HTTP メソッドを選択して記述した内容を追加できます。 - Add Info
Info の追加
既に記述している場合は、編集することができます。 - Add External Documentation
外部ドキュメントを追加 - Add Tag Declarations
タグ宣言を追加 - Add Tags To Operation
記述している Path を選択してタグを追加できます。 - Add Servers
サーバーを追加
Swagger Codegen
OpenAPI からソースコードを生成するコードジェネレータ
Swagger ドキュメントを解析して、異なる言語でクライアントコードを生成するテンプレート駆動型エンジンです。
YAML ファイル
Swagger のサンプルにある Petstore API を参考に必須部分の YAMLを記述してみます。
-
openapi オブジェクト
1openapi: 3.0.1 -
info オブジェクト
123456789info:title: 雑貨店version: 1.0.0description: >-雑貨店 API の概要これはサンプルです。license:name: Apache 2.0url: 'http://www.apache.org/licenses/LICENSE-2.0.html' -
paths オブジェクト
12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394paths:'/goods/{goodsId}':get:tags:- goodssummary: IDで雑貨を見つけるdescription: 単一の雑貨を返します。operationId: getGoodsByIdparameters:- name: goodsIdin: pathdescription: 返す雑貨のIDrequired: trueschema:type: integerformat: int64responses:'200':description: 成功content:application/json:schema:$ref: '#/components/schemas/Goods'application/xml:schema:$ref: '#/components/schemas/Goods''400':description: 無効なIDが指定されましたcontent: {}'404':description: 雑貨が見つかりませんcontent: {}security:- api_key: []post:tags:- goodssummary: フォームデータでストア内の雑貨を更新します。operationId: updateGoodsWithFormparameters:- name: goodsIdin: pathdescription: 更新する必要がある雑貨のIDrequired: trueschema:type: integerformat: int64requestBody:content:application/x-www-form-urlencoded:schema:properties:name:type: stringdescription: 雑貨の名前を更新status:type: stringdescription: 雑貨のステータスを更新responses:'405':description: 無効な入力content: {}security:- goodsstore_auth:- 'write:goods'- 'read:goods'delete:tags:- goodssummary: 雑貨を削除します。operationId: deletePetparameters:- name: api_keyin: headerschema:type: string- name: goodsIdin: pathdescription: 削除する雑貨IDrequired: trueschema:type: integerformat: int64responses:'400':description: 無効なIDが指定されましたcontent: {}'404':description: 雑貨が見つかりませんcontent: {}security:- goodsstore_auth:- 'write:goods'- 'read:goods'
エディタで使用
エディタのエクステンションとして使用することができます。
VS Code
VS Code には「OpenAPI (Swagger) Editor」や「Swagger Viewer
」エクステンションがあります。
インストール
EXTENSIONS: MARKETPLACE で「swagger」または「openapi」と入力すると、エクステンションが表示されるので選択してインストールを行います。
OpenApiのjsonを選択すると左に「OpenAPI」アイコンを表示されるので選択すると使えるようになります。「Swagger Viewer」と一緒に使うとWeb版と同様な編集とプレビューが同時にできます。
備考
SwaggerHubは、OpenAPI 仕様をクラウド上で設計、ドキュメント生成できる統合環境で、とても便利です。クラウドでの作業に問題なければこちらのほうがより洗礼されているようですので、おすすめです。
また、Swagger Codegen からフォークした OpenAPI Generator もあるようです。
関連リンク
- OpenAPI Specification
https://github.com/OAI/OpenAPI-Specification - OpenAPI Initiative
https://www.openapis.org - Swagger Tools
https://swagger.io/tools/ - SwaggerHub
https://swagger.io/tools/swaggerhub/ - OpenAPI Tools
https://github.com/OpenAPITools