swagger-api / swagger-api/swagger-ui

Path-level parameters should be listed before operation-level parameters

Open
#7,482 3 comments 1 reaction 1 assignee View on GitHub

@char0n is already working on this.

Since Sep 30, 2021.

cat: rendering version: 3.x version: 4.x
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: Windows 10
  • Browser: Chrome, Firefox latest
  • Method of installation: https://editor.swagger.io
  • Swagger-UI version: 3.52.0
  • Swagger/OpenAPI version: any
Content & configuration

Example Swagger/OpenAPI definition:

openapi: 3.0.0
info:
  title: test
  version: 0.0.0
paths:
  /something/{id}:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
    get:
      parameters:
        - in: query
          name: foo
          schema:
            type: string
      responses:
        '200':
          description: ok
Describe the bug you're encountering

In the API definition provided above, the /something/{id} path has path-level parameter id, plus the GET operation defines an additional parameter foo.

Swagger UI renders the path-level parameter id AFTER the operation-level parameters foo. This is often undesirable because path-level parameter list often contains in: path parameters (which are required), so it makes more sense to render path-level parameters first.

To reproduce...

Steps to reproduce the behavior:

  1. Paste the sample API definition into https://editor.swagger.io.
  2. Expand the operation.
Expected behavior

Parameter order is: id first, then foo.

Actual behavior

Parameter order is: foo, id.

Screenshots

image

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.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.