swagger-api / swagger-api/swagger.io-docs
/employees example in "Media Types" summary inaccurately describes response schema
Nobody has claimed this yet.
- Dominant language
- Astro
- Stars
- 1.6k
- Forks
- 407
- Avg merge
- 2m
- Merged PRs (30d)
- 2
Description
On https://swagger.io/docs/specification/v3_0/media-types/ the example path is /employees and its summary says "Returns a list of employees." However, the response schema is
type: object # Data type
properties:
id:
type: integer
name:
type: string
fullTime:
type: boolean
example: # Sample data
id: 1
name: Jessica Right
fullTime: true
Given that the path name is plural and the summary specifies "a list," I think that schema was meant to have been an array?
I don't think this technically impacts what this page of the documentation conveys, but it is confusing.
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
Open the Media Types documentation page and inspect the /employees example, comparing its summary with the response schema and sample data. Update the example so the path description and schema agree, then verify the rendered page shows the corrected example.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 48/100