まえがき
社内向けのメモとして書いたら、「これQiitaに上げたらいいんちゃう？」って言われたので上げます。
ほんとにOpenAPIとかSwagger始めて触るチームで共有する用に書いたので、おかしなところがあったら教えてください。
これ書いてる自分もSwagger始めて触ります。
これ書いたときの状況はこんな感じ。
- Webアプリ開発中で、チーム全員がVSCodeを使っている。
- チームで使えるSwagger Editorの環境を作った直後。
- タスク管理はJIRA
- 内部ドキュメント系はConfluenceで管理
はじめに
Swagger Editorが動くサーバも立てて、「さて、swagger使うか！」とは言うものの、書いたspecはどうやって管理する？
ってことを考えていろいろやったことメモ。
TL;DR
specはソースと一緒にgit管理するのがいいんじゃない？
ついでにvscodeのsettings.jsonにswaggerのjson schema読み込ませる設定書いて、jsonでIntellisence使って書くのがストレスフリー。
Extensions探せばSwagger Previewとかもあるし。
まずSwaggerってどう使うの？
最初にぶち当たった疑問がコレ。何にも知らない脳内イメージだと
- サーバでswaggerのソースが管理されてて
- 編集したいソースを選んで編集できて
- API仕様書として使えるようなページも勝手にできてる
とかいう妄想してた。
でも現実はそんなに甘くはなかった。
- Swagger Editorはその名の通りエディタを提供するだけ
- Swaggerのspecは別に管理する必要がある
- 仕様書のような見た目で表示しようと思ったら、Swagger Editorのプレビューを使うか、Swagger UIを使うしかない
- API仕様を公開しようと思ったら、自分で別途サーバを立てなければいけない（Swagger Editorが仕様書用サーバのコードを吐いてくれるけど）
けっこうめんどくさい。
Swaggerのspecどこで管理する？
というわけでタイトルの問題が出てきました。
適当に考えた候補は次の通り。
- Confluence
- API仕様のためのリポジトリでGit管理
- Productionコードと一緒にGit管理
まずひとつめ。これって今までと変わらなくない？というかSwagger Editorに食わせるぶんめんどうになっただけでは…。
つぎ、ふたつめ。管理するリポジトリが増えてくのつらいことないかな…。
みっつめ。これが一番無難なのでは。
良い意見あったらください。
Swagger Editorに毎回spec食わせるのめんどくさい問題
サーバ立てといて何言うとんねん、というやつですが気にしない。めんどくさいものはめんどくさい。
せっかくvscodeでソース見るついでにSwagger spec開けるんだからそこで編集もできないかなーとか思うわけです。
で、見つけました。Swagger Viewer。
Extensionsから探せばすぐ見つかります。これでvscode上でSwagger specのプレビューができる！
Swagger Editor開かなくてもAPI仕様が見れる！
…なんだけど。これだけじゃさすがにIntellisenseは効かない。
Swagger EditorだとIntellisenseっぽい機能がちゃんと用意されてるので、今のように初心者なうちはSwagger Editorの方が格段に書きやすいのです。
vscodeにIntellisenseを！
swagger specのIntellisenseを効かせてくれるExtensionsなんて誰かが作っててくれそうなもん…と思って探したものの、なかった。
用意されてないなんてことがあるのか…としょぼくれていると。
見つけました。Issueの中に、それっぽいことをしてる人が！
っちゅーことで、vscodeの設定にこれ書きましょう。
"json.schemas": [
{
"fileMatch": [
"*swagger.json"
],
"url": "http://json.schemastore.org/swagger-2.0"
}
],
fileMatchの中身は好きに設定してください。この設定だと、"swagger.json"で終わる名前のファイルはSwagger specだと思ってIntellisenseを効かせてくれるようになります。
これでSwagger Editorと同等のエディタに！Swagger Editorで使う機能はコード吐いてくれるところだけになったよ！
…あれ、specってyamlじゃないの？
気づいた人もいるかもしれませんが、Swagger Editorでは基本的にyamlでしか書けません。
Swagger Editorにコード吐かせようと思ったらyamlでペーストしないといけないし、Import from fileしたときにエクスプローラからフォルダ構成潜ってspecファイル探すのめんどくさい…。
と思ったのですが。
jsonで書いたspecをコピーしてSwagger Editorにペーストしようとすると、「yamlに変換しますか？」的なメッセージが出て勝手に変換してくれます！すばらしい！
これでもうvscodeで書かない選択肢がなくなりました。
まとめ
vscodeはすばらしい。