Swagger-editorの使い方兼気になったこと覚書

初めに

仕事でSwagger-Editorを使うことになった。
んだが日本語のドキュメントが見当たらないので使い方兼覚書を作成。
使い始めて1週間もたってないので気づいたことがあったら順次更新していく所存。

※後で清書する（とおもう）

英語でいいぞい、という人は↓とかで
https://github.com/swagger-api/swagger-editor

環境構築

↓をクリックすればswagger-editorが開く。楽。
http://editor.swagger.io/#/

Web上に会社のアレコレを書くのはちょっと…という人はDocker使うのが一番楽。
常に最新のバージョンが使えるのでいい感じ。
やることはDockerをターミナルで起動させた後、以下のコマンドをたたくだけ。
docker pull swaggerapi/swagger-editor docker run -p 80:8080 swaggerapi/swagger-editor

叩いた後、http://DockerのIP/#/ にアクセスすればswagger-editorが開く

因みに自動保存されるので、誤ってブラウザを閉じてしまっても再度開けば続きから編集できる。

基本的な使い方

右にプレビュー、左にエディター。
左上に各種メニューがあるのでそれらを簡単に説明。

File

• New -> 新規のYAMLファイルを作成
• Open Example -> サンプルが開ける。ミニマムセットからTwitterのAPIまでそろってる。ざっと眺めるだけでも使い方がわかる
• Paste JSON -> JSONファイルを張り付けるとYamlに書き出してくれる…のかな。使ったことない。
• Import File -> YAMLファイルを取り込む
• Download YAML -> YAMLファイルを出力
• Download JSON -> JSONファイルを出力

Preference

• Font Size -> そのまんま
• Editor Setting -> エディタの細かい設定ができる。Keybord Handlerからキーバインドを変えれるのが地味にうれしい(Emac,vim,sublimeの御三家も勢ぞろい)。
• Reset Editor Settings -> そのまんま
• Preferences... -> プレビューへの反映やらを設定。地味に重要
• Keypress debounce -> 何ミリ秒入力がなかったら変更がなくなったとみるか。↓のLive Renderingの反映までの時間だと思えばOK
• Live Rendering -> エディタでの修正をプレビューに自動反映するかどうか。チェック有で反映する。ファイルサイズが大きくなると処理が重くなるのでオフにするのも視野に。OFFにした場合は、プレビュー画面の最上部にリロードのリンクがでてくるようになる
• Auto-complete -> 自動保管機能。チェック有で保管する。のだがきかなくなるときもしばしば。F5更新で直る
• Pointer Resolution Base Path -> JSONの値を$refで参照した時のURL？よくわかってません。。。

Generate Server / Generate Client

選択したフォーマットでソースを吐き出してくれる。ほぼすべてカバーされて気がする。この機能により、ドキュメントから直接ソースを作れる

Help

ヘルプ。

書き方のアレコレ

ここからがメイン。細かい仕様は↓のURLから。英語だけどフィーリングで大体はわかる。
http://swagger.io/specification/

1階層目のスキーマのアレコレ

英語のドキュメントはこの場所

• swagger -> 使うバージョン。よほどのことがない限り2.0でデフォルトのまま。必須項目
• info -> ドキュメントのバージョンやタイトルなどを記載できる。必須項目
• host -> APIがやり取りするホスト名を記載できる。記載することでクライアント版のソースを吐き出したり、プレビュー画面から通信する際のホストとして機能する。無記載でswagger-editorが動いているホスト名が入る
• path -> swaggerのメイン要素。この下にURLパスの記載をしていく
• definitions -> swaggerのメイン要素。この下にレスポンスのパラメータを記載していく
• basePath -> ホストから連なる共通のパス。hostを「hogehoge.com」basePathを「moge/mage/」としたら、URLの始まは「http://hogehoge.com/moge/mage/～ 」となる
• schemes -> スキーム指定。http,https,ws,wssから選ぶ。
• produces / consumes -> MimeTypeの指定。選択肢はここを参照
• tags -> タグの説明を書ける。
• securityDefinitions -> セキュリティ周りの設定を書くならここ。よくわかってない。
• security -> セキュリティ周りの設定。よくわかってない
• parameters -> パラメータ周りの記載をまとめられる。pathを書く中で個別に定義することもできるが、構造化の観点を考えるならこちらに集約したほうがよさそう

Pathの記載のアレコレ

英語のドキュメントはこの場所
ほとんどはサンプル見たほうが早いので細かい文法などは割愛。自分が書いてるときに気になったことなどを載せていきます

• タグはつけたほうが良い。ただし複数はつけないほうが良い
• tagsを使うことでプレビュー側でフィルタリングできるので機能毎にタグ名を決めてつけるとよい。さらにソースを吐き出したとき、タグ名でAPIがまとまるようになる。が、複数つけると両方のクラスに含まれるようになってしまう。

例えばタグとして「Users」と「need-login」とつけた場合、Javaで吐き出すとそのPathにアクセスするAPIは「UsersAPI.java」と「NeedLoginAPI.java」の2つに全く同じものができてしまう

• enum型をparametersに指定できるが、その場合、「in」のフィールドを「body」にしないといけない...？さらにbodyを指定すると複数のデータが持てなくなる？しかし一方でresponse側で指定する分には問題ない。
• 「name」と「in」のフィールドは必須項目。

responsesの記載のアレコレ

共通のレスポンスを記載する
用途としてはエラー系のレスポンスをここに書いておけば、pathの中で$refで参照できる
すべてのresponseをここに記載して、ここからdefinitionsを参照するようにしてやると構造化できて良さそう

parametersの記載のアレコレ

共通のパラメータを記載する。
pathで使うparametersの値はここのものを参照するようにすれば整理できて良さそう

enum型っぽく使う場合は一工夫必要(↓の例で、apple,orange,melon個別に含める/含めないが選べる)

selling_flute:
　name: flute
　in: query
　type: array
　collectionFormat: multi
　uniqueItems: true
　items:
　　type: string
　　enum:
　　　- apple
　　　- orange
　　　- melon

こっちの例だとandroid/iphoneどちらかを選択する

　device_type:
　　name: type
　　in: formData
　　description: 端末のタイプ(android / iphone)
　　required: true
　　type: string
　　enum:
　　　- android
　　　- iphone

definitionsの記載のアレコレ

ほとんどはサンプル見たほうが早いので細かい文法などは割愛。自分が書いてるときに気になったことなどを載せていきます

• データタイプはここを参考にtypeとformatの組み合わせを決める。