在Swagger UI的参数列表中显示json对象属性

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": "test@test.com",
   "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?

Answer 1

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.