swagger
VSCode
OpenAPI

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

まえがき

社内向けのメモとして書いたら、「これ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はすばらしい。