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を１つに結合)

SwaggerでAPI設計した人なら、誰しも"１つのファイルに全部詰め込むの辛すぎぃ"という場面に遭遇したと思う。

URLやレスポンスボティは別のファイルに切り出した方が、後から改修はしやすい

なんで、複数のファイルを結合して１つのファイルに出力するためにswagger-merger(https://www.npmjs.com/package/swagger-merger)を使った

ymlファイルを変更するたびに、src/swagger.yml (Redocで監視しているファイル）を自動で更新するようGulpを使うことにした。

gulpfile.js

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);
}

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で複数のファイルを１つに結合できる
それをdockerで立ち上げたのがswagger-monster(https://github.com/smithshiro/docker-swagger-monster)

おっしまい^^