swagger-api / swagger-api/swagger-codegen

Petstore example swagger has undocumented responses

Open
#8,603 1 comment 1 reaction 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.