swagger-api / swagger-api/swagger-ui
Nested schemas do not show description in swagger-ui
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 29k
- Forks
- 9.3k
- Avg merge
- 2d 23h
- Merged PRs (30d)
- 25
Description
- OS: macOS 10.14
- Browser: Safari
- Version: 12.0
- Method of installation: Github download
- Swagger-UI version: 3.20.5
- Swagger/OpenAPI version: Swagger 2.0
The following snippet of Swagger JSON from my API includes a description for a nested property:
"reasonForDeletion":{"description":"The reason for deletion. VocabularyDomain=SubjectMgmtAllergyDeletionReason.","$ref":"#/definitions/CodedConceptReference"}}
The Swagger-ui output, however, does not display the nested entity description i.e.: it looks like this:

Steps to reproduce the behavior:
- Use Swagger-UI to explore an API with a nested property having a description
- Expand the nested property
- Observe a lack of the 'description' text
Expected behaviour:
Descriptions of nested properties should appear immediately adjacent to the described property; the nested entity descriptions should then follow
Additional context or thoughts
- this problem has existed in every version of Swagger-UI going back well over a year. It has been reported several times, and described as 'fixed' several times as well
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 reproducing the issue in Swagger UI 3.20.5 with the supplied Swagger 2.0 JSON and inspect the nested-property rendering path. Done means the description for reasonForDeletion appears adjacent to that property when it is expanded, including a regression check for the reported case.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, openapi
- Domain
- documentation, frontend
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 35/100