ども、シローです。
一応、100記事目です。よーがんばった
で、今回はAPIの定義書を作成するツールを作ったので、そのご紹介。
API定義書ってそもそも必要?
チーム開発するとAPIを実装するじゃないですか、サーバの人は。
で、その実装する内容をドキュメントとして残した方がいいのか・・
デメリット、メリット含めて僕の意見としては
デメリット
- API定義書を作成する工数がかかる
- API定義書を修正する工数がかかる
- Swaggerのようなフォーマットを覚えるのが面倒い
時間かかるし、面倒いよね。。
必ずしも作るのが正義とは思わんよ。
メリット
- 非エンジニアでもAPIの挙動をある程度把握できる(実際のAPIと多少差異があったとしても、PMには喜ばれる)
- フロント、サーバと役割が完全に分担されていれば、情報伝達の際に便利
よし、メリット:デメリット = 2 : 3なので
デメリットが多い、API定義書は作らなくていい、はい解散!
実際作ったの
それでも、API定義書を作らなきゃダメなんだよ。。
という方たちに向けて、API定義書を作成する基盤を作りました。
リポジトリ名:(https://github.com/smithshiro/docker-swagger-monster)
100記事目に達したんだからさ、モンスター一本くらい奢ってよという意味合いでswagger-monster
にした。
もう、このブログの読者ならリポジトリクローンしてわちゃわちゃしたら、やりたいことはできると思う。
なんで、どうやって作ってんの?って方達にもうちょっと詳しく説明する。
Redoc (SwaggerのymlファイルをHTMLに変換してくれる)
上のリポジトリを立ち上げるとhttp://localhost:18080
で
のような画面が立ち上がるはずななのだけど、
これはsrc/api/swagger.yml
の内容をHTMLに変換しているものであって、それを実現するためのツールがRedoc(https://redocly.github.io/redoc/)
docker-compose.yml
の中にredocly/redoc
というイメージからredoc
コンテナを立ち上げていて、それがRedocを動かして上のような画面を出力している。
Swagger-merger(複数のSwaggerのymlを1つに結合)
SwaggerでAPI設計した人なら、誰しも"1つのファイルに全部詰め込むの辛すぎぃ"という場面に遭遇したと思う。
URLやレスポンスボティは別のファイルに切り出した方が、後から改修はしやすい
なんで、複数のファイルを結合して1つのファイルに出力するためにswagger-merger(https://www.npmjs.com/package/swagger-merger)を使った
ymlファイルを変更するたびに、src/swagger.yml
(Redocで監視しているファイル)を自動で更新するようGulpを使うことにした。
gulpfile.js
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
const { watch } = require('gulp'); const { exec } = require('child_process'); function swaggerMerge(cb) { const command = "npm run merge" exec(command, function (err, output, code) { if (err || code.length > 0) { console.log('===Failed to merge===') console.log(code) } }) cb(); } exports.default = () => { watch(['api/**/*.yml','!api/swagger.yml'], swaggerMerge); } |
docker-compose.yml
でswagger-merger
というコンテナで立ち上げ時にgulpを起動している。
なので、API定義書を編集してブラウザ(http://localhost:18080)をリロードすると更新されるようになっている。
最後に
API定義書みたいなドキュメント作成って正直だるいよね
あくせく作ったくせに、その保守もしないといけないし(結局他の人がそれを引き継ぐことってあんまないし)
けど、ある程度規模が大きいプロジェクトの開発だと、残しておいた方が
- 現場のPM
- 新しく開発に携わるメンバー
には喜ばれるとは思う。
そして、こういったものを作ったみたいなアピールとかしとけば、社内のエンジニアとしての評価が上がったり、上がらなかったり。
(僕は上がらなかったけど)
というわけで、利用したいと思った人は使ってくれよな(そして、Twitterもフォローよろ、モンスターも奢れ、etc...)
まとめ
- RedocでSwaggerファイルをHTMLに出力する
- swagger-mergerで複数のファイルを1つに結合できる
- それをdockerで立ち上げたのがswagger-monster(https://github.com/smithshiro/docker-swagger-monster)
おっしまい^^