swagger-api / swagger-api/swagger-ui
Path Summary and Description Not Rendered
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 29k
- Forks
- 9.3k
- Avg merge
- 2d 23h
- Merged PRs (30d)
- 25
Description
Q&A (please complete the following information)
- OS: macOS Mojave 10.14.6
- Browser: Chrome
- Version: 77
- Method of installation: SaaS
- Swagger-UI version: Swaggerhub
- Swagger/OpenAPI version: OpenAPI 3.0.0
Content & configuration
https://app.swaggerhub.com/apis/vacasa5/Simple/1.0.0
Example Swagger/OpenAPI definition:
openapi: 3.0.0
servers: []
info:
description: This is a simple API
version: "1.0.0"
title: Simple Inventory API
contact:
email: you@your-company.com
license:
name: Apache 2.0
url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
tags:
- name: admins
description: Secured Admin-only calls
- name: developers
description: Operations available to regular developers
paths:
/inventory:
summary: this summary isn't rendering
description: neither is this description
get:
tags:
- developers
summary: searches inventory
operationId: searchInventory
description: |
By passing in the appropriate options, you can search for
available inventory in the system
parameters:
- in: query
name: searchString
description: pass an optional search string for looking up inventory
required: false
schema:
type: string
- in: query
name: skip
description: number of records to skip for pagination
schema:
type: integer
format: int32
minimum: 0
- in: query
name: limit
description: maximum number of records to return
schema:
type: integer
format: int32
minimum: 0
maximum: 50
responses:
'200':
description: search results matching criteria
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/InventoryItem'
'400':
description: bad input parameter
post:
tags:
- admins
summary: adds an inventory item
operationId: addInventory
description: Adds an item to the system
responses:
'201':
description: item created
'400':
description: 'invalid input, object invalid'
'409':
description: an existing item already exists
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InventoryItem'
description: Inventory item to add
components:
schemas:
InventoryItem:
type: object
required:
- id
- name
- manufacturer
- releaseDate
properties:
id:
type: string
format: uuid
example: d290f1ee-6c54-4b01-90e6-d701748f0851
name:
type: string
example: Widget Adapter
releaseDate:
type: string
format: date-time
example: '2016-08-29T09:12:33.001Z'
manufacturer:
$ref: '#/components/schemas/Manufacturer'
Manufacturer:
required:
- name
properties:
name:
type: string
example: ACME Corporation
homePage:
type: string
format: url
example: 'https://www.acme-corp.com'
phone:
type: string
example: 408-867-5309
type: object
Swagger-UI configuration options:
SwaggerUI({
// your config options here
})
?yourQueryStringConfig
Describe the bug you're encountering
Under the /paths/pathName the spec allows a summary and description that applies to the entire endpoint. Those values are not rendered.
To reproduce...
Steps to reproduce the behavior:
Add a summary and description under a path
Expected behavior
Swagger UI would render the summary and description in a way that made it clear it applied to all operations
Screenshots

Additional context or thoughts
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 with the supplied OpenAPI 3.0 YAML, especially the summary and description under paths./inventory, and reproduce it in Swagger UI. Trace how path-level metadata is rendered alongside its operations; done means the path summary and description appear clearly as applying to all operations, with coverage for this example.
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
- Mostly clear
- Newbie friendliness
- 35/100