APIドキュメントを実装と乖離させないために - Qiita

内部用APIであるか外部の開発者向けのAPIであるかに関わらず、ドキュメントと実装との乖離は極力避けたいものであるが、注意深く開発を進めない限りこの状況は容易に起こり得る。何が乖離を引き起こし、どうすればこの状況を回避できるのか考えながら、JSON Schemaの利用例を紹介する。なおこの投稿では、HTTP経由でデータの通信を行うような狭義のAPIのことをAPIと呼ぶことにする。 同じ情報源を参照する APIドキュメントと実装が同じ情報源を参照するようにすれば、論理的に関連した要素は統一的に変更され、これらの変更は完全に同期が取れたものになる。つまり、変更時に乖離が生じにくくなる。但し情報の見せ方によって乖離が発生する可能性は十分にだろうし、乖離が発生するのは理解しようとする側の認識の問題であるから、論理的に全く起こり得ないということではない。 この参照の形には、両者が別の情報源を参照する

[vvakame]

ちょっと討論してみたいなーこれ。Google Discovery Based ServiceやSwagger、RAMLなど類似のアイディアのものがあるがなぜJSON Schema生なのか？

[tbpg]

“JSON Schema (とその周辺ツール) を利用せずとも同等の成果物を得ることは可能だが、利用する方がより短い時間で実現できるため利用している”

[takaesu]

APIドキュメント

[lizy]

XML SchemaからJSON Schemaへの進化？もうちょっと人に優しくならないものなのか

[mano-junki]

設計　実装　api tips hack システム開発　json schema jsonschema フェーズ間設計

[marmotY]

HTTPを使ったデータ入出力と永続化の一種の究極系。行指向が良いのはバージョン管理しやすいから。マイグレーションのようにデータ形式そのもののバージョン管理も出来ると良い。