swagger-api / swagger-api/swagger-ui

Fetch schema description when used for parameter

Open
#5,089 1 comment 1 reaction 0 assignees View on GitHub

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.

https://stackoverflow.com/questions/53828430/how-to-use-the-same-definition-for-an-id-parameter-and-an-id-schema-property/53829788#53829788

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.