swagger-api / swagger-api/swagger-ui

Path Summary and Description Not Rendered

Open
#5,653 5 comments 4 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

cat: style & presentation specification: 3.x type: enhancement
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

image

Additional context or thoughts

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.