Swagger Docker Gulp

Docker + Redoc + SwaggerでAPIドキュメントサービスを作ってみた

ども、シローです。

一応、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

docker-compose.ymlswagger-merger というコンテナで立ち上げ時にgulpを起動している。

なので、API定義書を編集してブラウザ(http://localhost:18080)をリロードすると更新されるようになっている。

最後に

API定義書みたいなドキュメント作成って正直だるいよね

あくせく作ったくせに、その保守もしないといけないし(結局他の人がそれを引き継ぐことってあんまないし)

けど、ある程度規模が大きいプロジェクトの開発だと、残しておいた方が

  • 現場のPM
  • 新しく開発に携わるメンバー

には喜ばれるとは思う。

そして、こういったものを作ったみたいなアピールとかしとけば、社内のエンジニアとしての評価が上がったり、上がらなかったり。

(僕は上がらなかったけど)

というわけで、利用したいと思った人は使ってくれよな(そして、Twitterもフォローよろ、モンスターも奢れ、etc...)

まとめ

おっしまい^^

 

-Swagger, Docker, Gulp

© 2023 Shiro's secret base