swagger-cli validate does not ensure unique operationIds
olivierbeaulieu opened this issue · 0 comments
As per the OAS 3.0.3 spec, for operation objects, operationIds must be unique:
Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is case-sensitive. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.
Considering the following spec - notice how the two operations share the same operationId: notUniqueOperationId
. swagger-cli validate openapi.json
returns openapi.json is valid
.
However https://editor.swagger.io/ will properly report Semantic error at paths./pet.post.operationId Operations must have unique operationIds.
{
"openapi": "3.0.2",
"info": {
"title": "Swagger Petstore - OpenAPI 3.0",
"version": "1.0.7"
},
"servers": [{ "url": "/api/v3" }],
"tags": [
{
"name": "pet",
"description": "Everything about your Pets"
}
],
"paths": {
"/pet": {
"put": {
"tags": ["pet"],
"summary": "Update an existing pet",
"description": "Update an existing pet by Id",
"operationId": "notUniqueOperationId",
"requestBody": {
"description": "Update an existent pet in the store",
"content": {
"application/json": { "schema": { "$ref": "#/components/schemas/Pet" } }
},
"required": true
},
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": { "schema": { "$ref": "#/components/schemas/Pet" } }
}
}
}
},
"post": {
"tags": ["pet"],
"summary": "Add a new pet to the store",
"description": "Add a new pet to the store",
"operationId": "notUniqueOperationId",
"requestBody": {
"description": "Create a new pet in the store",
"content": {
"application/json": { "schema": { "$ref": "#/components/schemas/Pet" } }
},
"required": true
},
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": { "schema": { "$ref": "#/components/schemas/Pet" } }
}
}
}
}
}
},
"components": {
"schemas": {
"Category": {
"type": "object",
"properties": {
"id": { "type": "integer", "format": "int64", "example": 1 },
"name": { "type": "string", "example": "Dogs" }
},
"xml": { "name": "category" }
},
"Tag": {
"type": "object",
"properties": {
"id": { "type": "integer", "format": "int64" },
"name": { "type": "string" }
},
"xml": { "name": "tag" }
},
"Pet": {
"required": ["name", "photoUrls"],
"type": "object",
"properties": {
"id": { "type": "integer", "format": "int64", "example": 10 },
"name": { "type": "string", "example": "doggie" },
"category": { "$ref": "#/components/schemas/Category" },
"photoUrls": {
"type": "array",
"xml": { "wrapped": true },
"items": { "type": "string", "xml": { "name": "photoUrl" } }
},
"tags": {
"type": "array",
"xml": { "wrapped": true },
"items": { "$ref": "#/components/schemas/Tag" }
},
"status": {
"type": "string",
"description": "pet status in the store",
"enum": ["available", "pending", "sold"]
}
},
"xml": { "name": "pet" }
}
}
}
}