Postmanのドキュメント機能をRails APIで試す
Takayuki NagatomiPostman、ユーザー登録が全機能を使うには必須になってredditとかでは避けられてるけど、高機能になってワークスペース機能とかもできてるみたいでユーザー機能が逆に便利だったりするのかも。
Takayuki Nagatomi例えばこんな感じにドキュメントが出力できるようだ。
Takayuki Nagatomi理想的にはリクエストとかレスポンスとかはキャプチャしてもらって説明だけ書き足すという形がやりたい。
Takayuki NagatomiなんかRails APIのサンプルリポジトリを拾ってきてそれを対象にやってみる。
Takayuki Nagatomiそれっぽいのが見つからない。自分で作ったほうが早いかも。
Takayuki NagatomiChatGPTに聞いてみてる
Takayuki Nagatomirspec-openapi でrequest specからOpenAPIスキーマを吐き出して、それをPostmanにインポートしたうえで編集するというのが良いような気がしてきた。
Takayuki Nagatomiサンプルでrequest specまで書くのは面倒なので、スキーマをインポートしたていで編集してみる。
Takayuki Nagatomiその前にimport data from a Git repositoryという機能があるっぽいのでやってみる。
Takayuki Nagatomiサポートされている定義形式はこのあたりなのかな？
OpenAPI 3.0 and 3.1
Swagger 1.2 and 2.0
Protobuf 2 and 3
GraphQL
cURL
RAML 0.8 and 1.0
WSDL 1.1 and 2.0
HTTP Archive (HAR)
Web Application Description Language (WADL)
Takayuki Nagatomiインポートを試みる
Takayuki Nagatomiダメだった。
リポジトリの中の定義ファイルを探してるだけっぽい？
Railsのroutesからいい感じにとかやってくれるものではなかった。
Takayuki Nagatomiさぁ、これを読んでいこう
Takayuki Nagatomiあ〜OverviewっていうところでWYSIWYGで書いていくのか。
Takayuki Nagatomiん〜色々機能は豊富そうだが、ロックインされるのと、誰がメンテするか問題が発生しそうなので、自分のニーズ的にはautodocで適切なspecに autodoc: true をつけるで良い気がしてきた。
それはそれでautodoc固有のコードを残すことになるんだけど、外すのはそんなに苦労しないだろうし。
Takayuki Nagatomi概要が分かったところでいったんおしまい。