REST APIドキュメント生成パターン - ✘╹◡╹✘

REST API用のドキュメントを生成するときにどうやってるかについて雑記を残しとく。 概要 実装とドキュメントの乖離を避けるためには、同じ意味情報を二箇所以上に定義することを避ける必要がある。そのための方法として、実装それ自身か、もしくは実装が参照している何らかのメタデータを元にしてドキュメントを生成したり、テストの実行結果からドキュメントを生成するというパターンがある。 テストから Cookpadでは、autodocというライブラリを利用して、RSpecでテストを実行している途中で得られたメタデータからドキュメントを生成している。これはテストの実行結果からドキュメントを生成するパターン。 これは実現方法としてはかなり特殊な部類。このパターンが最も効果的に働くのは、ドキュメント生成のために余分な開発コストはあまり掛けたくないが、テストは真面目に書いている OR 真面目に書いてほしい、とい

[mcddx30]

“良いコードを書いたら良いドキュメントが生成される、という風にしておくのが丁度良いと思う。”

[kakku22]

ある程度組織の規模が大きくウォーターフォール感のある人がリーダーだと「まず設計をチーム全体で合意取って」みたいなこと言うしメタデータからの生成が良いって結論になりそう

[yosshi1202]

「概念投げたら最高の具象になって返ってくる世界が最高。」

[hirocueki]

あいだみつおじゃないが「コードがさき、ドキュメントがあと」がいい。良いドキュメントで包まれた悪いコードより絶対“良いコードを書いたら良いドキュメントが生成される、という風にしておくのが丁度良いと思う”

[efcl]

テストから、メタデータ(yaml -> json schema)から、コードから APIドキュメントを生成するかについて

[scndhnd]

"出来れば実装からメタデータを生成して、そこからドキュメントを生成するというのが理想的" "良いコードを書いたら良いドキュメントが生成される"

[K2ICE]

“短期的にすぐメリットが享受出来るという実感がないと人間はやらないし、まあその辺の分かりやすい餌として便利なドキュメントが生成出来ますというメリットを謳って釣っていくのがいいと思う。”

[farako]

「良いコードを書いたら良いドキュメントが生成される、という風にしておくのが丁度良いと思う」