説明
operationIdはAPI操作を識別する値で、定義する場合はAPI全体で一意である必要があります。異なるエンドポイントやメソッドで同じ値を使うと、コード生成器、SDK、文書ツールが操作を区別できない場合があります。
想定される影響
SDKのメソッド名の衝突や誤った操作への参照により、生成や連携でエラーが発生する可能性があります。
対処方法
定義したoperationIdの重複を確認し、各操作の目的を表す名前を使用してください。名前を変える場合は、それを参照するリンク、生成クライアント、自動化も更新してください。
例
OpenAPI 3.0の操作識別子だけを比較する抜粋です。文書のinfoと各操作に必要なresponsesは省略しています。
変更前
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"operationId": "operation_id"
},
"post": {
"operationId": "operation_id"
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"operationId": "listRootResource"
},
"post": {
"operationId": "createRootResource"
}
}
}
}
変更前はGETとPOSTに同じ識別子を使っています。変更後は取得と作成の操作を区別します。識別子を変えるだけでサーバーのパスや動作が変わるわけではありません。