swagger-api / swagger-api/swagger-ui
Fetch schema description when used for parameter
Open
Nobody has claimed this yet.
type: support
- Dominant language
- JavaScript
- Stars
- 29k
- Forks
- 9.3k
- Avg merge
- 2d 23h
- Merged PRs (30d)
- 25
Description
Content & configuration
Swagger/OpenAPI definition:
openapi: 3.0.0
info:
title: Test API
version: 1.0.0
paths:
/foo/{user_id}:
get:
parameters:
- $ref: '#/components/parameters/user_id'
responses:
'200':
description: A user
content:
application/json:
schema:
$ref: '#/components/schemas/User'
components:
parameters:
user_id:
name: user_id
in: path
required: true
schema:
$ref: '#/components/schemas/UserId' # <-------
schemas:
UserId:
type: string
description: The ID of a User
example: abcdef
User:
type: object
properties:
id:
$ref: '#/components/schemas/UserId' # <-------
Is your feature request related to a problem?
The parameter is able to fetch the UserId's example but not the UserId's description
Describe the solution you'd like
The parameter's description should equal the UserId schemas' description.
Additional context
My original Stack Overflow question on defining an ID that is shared in a parameter and schema once.
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 loading the provided OpenAPI 3.0 definition in Swagger UI and trace how the parameter reference resolves its schema metadata. Done means the user_id parameter displays the UserId schema description, “The ID of a User,” while retaining the existing example behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100