RailsでつくるAPIサーバのドキュメントを自動生成してくれるAutodocを使っていて気をつけること

Autodocとはなんぞやという方はこちらの記事を参照。 公式はこちら

で、大変便利なAutodocだけど、注意点が２つ。

まず一点目はRspc3で動かない点。プルリクが上がってるが、取り込まれてない。

なので、forkして使ってる人が結構いる感じ。

２点目、通信が発生しているところでマークダウンが生成されるので、shared_exampleとか使って、そこで実際の通信が発生するようなものは、ドキュメントが全てshared_exampleがあるファイル名で生成されてしまう。

具体的に言うと、例えばこちらの記事のようなヘルパーメソッドを用意して、これでAUTODOC=1でAPIのテストを全て行った場合、shared_exmpleを呼び出している個別のspecファイルではなく、doc/support/api_helper.mdというドキュメントが生成されてしまう。

こうなるのは仕方がない気がするので、autodocを使ってドキュメントを生成する場合は、Autodocで記録する個別のexampleの中でgetやpostを投げる感じで。