swagger-api / swagger-api/swagger-codegen
Petstore example swagger has undocumented responses
Nobody has claimed this yet.
- Dominant language
- Mustache
- Stars
- 17.8k
- Forks
- 6k
- PR merge metrics
- No merged PRs in 30d
Description
Description
I can't list all occurences, but the petstore example swagger has a number of cases where the methods have totally missing responses based on their actual server logic.
For example in the following method, POST /pet only has invalid input documented. however it returns 200 when a pet is created.
"/pet": {
"post": {
"tags": [
"pet"
],
"summary": "Add a new pet to the store",
"description": "",
"operationId": "addPet",
"consumes": [
"application/json",
"application/xml"
],
"produces": [
"application/xml",
"application/json"
],
"parameters": [
{
"in": "body",
"name": "body",
"description": "Pet object that needs to be added to the store",
"required": true,
"schema": {
"$ref": "#/definitions/Pet"
}
}
],
"responses": {
"405": {
"description": "Invalid input"
}
},
"security": [
{
"petstore_auth": [
"write:pets",
"read:pets"
]
}
]
},
Similarly PUT /pet only has 3 4xx errors documented. This method has successful responses.
It looks like the petstore swagger needs reviewing based on the example server - because it's not in sync.
Swagger-codegen version
n/a
Swagger declaration file content or url
https://petstore.swagger.io/v2/swagger.json
Command line used for generation
Steps to reproduce
Related issues/PRs
Suggest a fix/enhancement
Suggested fix is to review the swagger based on the petstore server that you're hosting and verify that it matches.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by comparing the Petstore Swagger declaration at https://petstore.swagger.io/v2/swagger.json with the hosted example server behavior, beginning with POST /pet and PUT /pet. Review the documented responses for each operation and update the specification so successful and error responses match the server.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- api, documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100