Path Summary and Description Not Rendered

[naesean]

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: [email protected]
  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

[webron]

Thanks for the report, @naesean. You're correct in saying it's not rendered. This was an addition in OpenAPI 3.0, but it's one that doesn't really work well with how Swagger UI renders.

Since the operations are grouped based on tags (which is what the specification intends), and a single operation can appear in multiple tags, or otherwise, separate operations from a single path can appear under different tags, there's no easy way to present that information.

It's a bit of a UX challenge in terms of how to present it. You're welcome to suggest ideas though.

[naesean]

Rearrange the order of display to be endpoint first, with summary and description, then the methods. Tags could be treated as filters instead of part of the taxonomy.

[webron]

Unlikely to happen, though we may consider it. Tags are intended for grouping of operations, not filters.

[marko-galesic]

May create a pull request for this, but, for those like me that wanted some way of documenting an endpoint that roughly correlates to an entity and it's associated operations (looks like that was what @naesean's intention was). Here's what may be the start of solution/workaround:

A Google search got me Grouping Operations with Tags

A sample of how this might look like:

.
.
tags:
  - name: meta
    description: operations about the service, itself (e.g. whether the service is up)
paths:
  /api/meta/ready:
      get:
         tags:
          - meta
      .
      .
      .

Would be great to either:

• note the behavior for description and summary in the docs and link to the group operations with tags doc
• replace description and summary with a link to something tracking the work to present the info better and link to the group operations tags doc

[MBGoldberg-BD]

Just ran into this limitation as well. Trying to create robust documentation for our API but path description, although supported by the openAPI 3.0 spec, is not as useful if won't be rendered by Swagger UI.