Display json object properties in parameters list in Swagger UI

Question

I' writing the docs for web API with swagger, OpenAPI version 3. I use swagger php package to generate documented json from annotations. I have service, where I send post request to add new user, and requested body is json(so parameters are sent as json object). it has 2 parameters - email and password. request body looks like

{
   "email": "[email protected]",
   "password": "test"
}

here's YAML of swagger

paths:
  /users:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignUp'
      responses:
        '200':
          description: successful operation

here's reference schema which contains request parameters (/components/schemas/SignUp)

SignUp:
  title: SignUp
  description: Adds new user
  type:object
  required:
    - email
    - password
  properties:
    email:
      description: User's email
      type: string
      maximum: 255
      pattern: email
    password:
      description: User's password
      type: string
      maximum: 255

here's how it looks in swagger UI as you can see on image, requested body is empty(while I have 2 parameters) and this is the issue. if I change the header from application/json to application/x-www-form-urlencoded then it will work(it will show all parameters in parameters list). how to make it show json object parameters in that list?

Helen · Accepted Answer · 2018-07-20 09:04:58Z

2

Your spec is correct and the displayed result in Swagger UI is correct and exactly as expected for OpenAPI 3.0 definitions.

Note there are two sections, "Parameters" (for parameters) and "Request body" (for requestBody). In OpenAPI 3.0, parameters is only used for query parameters, path parameters, request headers and cookies; whereas requestBody is displayed in the "Request body" section. You can click "Model" link to view the request body schema with property descriptions.

answered Jul 20, 2018 at 9:04

Helen

99.8k17 gold badges280 silver badges352 bronze badges

Sign up to request clarification or add additional context in comments.

2 Comments

devnull Ψ Over a year ago

thanks for reply. I know about parameters and request body. so its not possible to show them in that list? I have models for it also, where everything is described, but I want to show this in list

Helen Over a year ago

It's not possible in the standard Swagger UI, but Swagger UI is open-source so you can fork and change it as you wish. But keep in mind that users familiar with the standard Swagger UI might get confused if things are displayed in unexpected places.

Collectives™ on Stack Overflow

Display json object properties in parameters list in Swagger UI

1 Answer 1

2 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

2 Comments

Your Answer

Sign up or log in

Post as a guest

Related