apipie をつかって, rails (api モード) の scaffold でつくった API に対して、ドキュメント作成をしてみた。
See https://github.com/katoy/rails5-sql/blob/master/Using-Apipie.md
API ドキュメントには、レスポンスの json 例を記載することは必須であるが、
apipie では、テストコードを走らせたときの json レスポンスをドキュメントに埋め込むことが可能。
次のような記載を追加してからテスト走らせたせれば、こんなリファレンスページができる。
api :GET, '/memos/:id', 'Show memos'
param :id, Fixnum, :desc => "User ID", :required => true
error 404, "Missing"
error 500, "Server crashed for some <%= reason %>", :meta => {:anything => "you can think of"}
meta :author => {:name => 'John', :surname => 'Doe'}
def show
# Nothing here, it's just a stub
end