APIのドキュメントってどうしようか?
という話の中で、メンバーからslateがいい感じらしいという推しがあり試してみました。
とりあえず動きを確認するという事で、DockerHubにあったslateを手っ取り早くdocker pullして動かします。
動きは確認出来たので、swagger-to-slateを使ってswaggerで作成してあったAPI仕様を変換し、作成されたmdファイルをindex.html.mdにリネームしてdocker-composeでボリューム指定します。
1 2 3 4 5 6 7 8 9 10 11 |
version: '3' services: slate: image: slatedocs/slate:latest volumes: - ../slate/source/index.html.md:/srv/slate/source/index.html.md #あとで - ../slate/source/includes:/srv/slate/source/includes ports: - 4567:4567 command: serve |
各言語向けの説明は別途書き込む必要がありますが、いい感じで表示されています。
index.html.md内のincludes部分にファイルを追加指定すれば、複数のファイルに分割する事が出来そう(初期インストールでは_errors.mdが配置されています)なので、index.html.md内はイントロや認証関連のみ記載し、includesで複数ファイル構成にするのがよさそうですね。