ReDocに食わせるOpenAPIにはoperationIdを書こう
最近ReDocを触っていてヤヤハマリに遭遇することがあるので書いておきます。
operationId
ってなにさというと、OpenAPIのOperation Objectの一項目で、操作を識別するための一意な文字列のことです。ReDocに食わせるOpenAPIには、と書きましたが、そうでなくても書いておくべきやつです。
困ったこと
v1.14.0の話です。
ReDocのデモを見るとわかりますが、例えばaddPet
というoperationIdが付いた操作には、パーマリンクとして
http://rebilly.github.io/ReDoc/#operation/addPet が与えられます。operationIdをちゃんと書いたときはいいのですが、ここをサボると、ReDocは他の情報から頑張って一意な文字列を作ろうとします。健気なやつです。ただその文字列が、
/#null%2Fpaths%2F~1v1~1pet.json%2Fget
みたいな。せっかく頑張ってくれたんですが、ちょっと積極的に使う気になれない。しかも場所によって先頭のnull
がundefined
になってリンクとして機能しないっていう…。ということで、operationIdはサボらずちゃんと書きましょう。