RailsをAPIとして利用する際のAPIドキュメントを業務で作成したのだが、思っていたより時間が掛かったので反省も含め書いていく。
1.色々調べてみた
最初、1から書くのは億劫だし楽に書く方法を調べたところ、GemにRspecから生成する方法があることを知り試してみた。
それっぽいものは直ぐに生成されたから便利ではあったが、Rspecが全てのControllerで書かれている訳ではなかったので、書かれてないControllerを探したりで時間が掛かってしまった。(素直に急がば回れをするべきだった。反省。)
2. 書いてはみたものの...
その後、あまり理解もしてないままOpenAPIの記法に従ってymlを書いていくが、理解してないため遭遇するエラーの解決速度が如何せん遅い。
この手のものは、全体から細部に書くべきだが、Pathを列挙することもなくただひたすら上から順々に書いてしまった。
### 今回のよくない進め方の例
"/line/message":
post:
summary: create
tags:
- Line::Message
requestBody:
content:
application/json:
と愚直に書いてた
おそらく正解の作業の進め方はこう。
この方がそもそも進めやすいし、進捗も把握しやすい
### この方がもれなく勧められたはず
"/line/message":
post:
responses:
get:
responses:
"/line/message/{id}":
put:
responses:
get:
responses:
また、書いていく際情報収集不足で、ymlに直接書いていたが世の中には便利なものがあるらしく書きやすいエディターが存在した
3. 記法について
特段私からいうことはなく、下記記事を参考に書くのが一番早い。
下記記事は各項目の詳細が書かれてるから一回読むべき
整理のためメモがてら記載。何か項目を書いたらtypeで型を常に指定してあげるイメージ
"/line/message":
HTTPメソッド:
parameters: or requestBody:
#parametersの場合
- name: user_id #paramsの名前と揃える.pathの値になるため
in: path or query #queryなら /line/message?user_id=値になる
required: true # 必須かどうかのフラグ
schema: #型とか詳細設定する場所
type: string
description: ユーザーID #nameで指定したkeyの説明書いたりでいいかな
example: U2525 #swagger editorで発行するqueryにそのまま入ってくれるから書いた方がわかりやすいし良いかも。
# requestBody
- content:
application/json: # xmlとか合わせる
schema:
type: object #schemaのtypeを指定。他にはarrayがある。その時はitems:必須
properties: # objectの必須
user_id:
type: string
example: U2525
message: #lineをイメージ
type: object
propertirs:
text:
type: string
type:
type: string #typeカラムの型をtype: stringで定義してるだけ。ややこしい
examples: # こんな感じで値によって分岐するような表記もできる
typeがwordの場合
value:
user_id: U2525
type: word
typeがimgの場合
value:
user_id: U2525
type: img
responses:
"200":
description: メッセージ作成完了 # このrequestの結果生じるreesponsを書くべきかな
4. 反省まとめ
- 初見の事象問わず、常に
全体から細部への考えを忘れずに作業すべき - チートシートなどで大枠を捕らえつつ、自分が書いてるコードの意味を調べて理解した上で書かないとエラーが生じた際に結局無駄な時間がかかる
- 今回だとpathとquery、requestBodyの理解が少し甘く知識不足面で時間を食った場面があったので、再度勉強するきっかけを得た。