Posted at

swagger specどうやって管理する問題

More than 1 year has passed since last update.


まえがき

社内向けのメモとして書いたら、「これ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なんて誰かが作っててくれそうなもん…と思って探したものの、なかった。

用意されてないなんてことがあるのか…としょぼくれていると。

https://github.com/Microsoft/vscode/issues/5334

見つけました。Issueの中に、それっぽいことをしてる人が!

っちゅーことで、vscodeの設定にこれ書きましょう。


settings.json

"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はすばらしい。