search
LoginSignup
16

More than 3 years have passed since last update.

posted at

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なんて誰かが作っててくれそうなもん…と思って探したものの、なかった。
用意されてないなんてことがあるのか…としょぼくれていると。

見つけました。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はすばらしい。

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
What you can do with signing up
16