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

Question

我正在使用swagger（OpenAPI版本3）编写Web API文档。我使用swagger php包从注释生成文档化的json。 我有服务，我在其中发送发布请求以添加新用户，并且请求的主体为json（因此参数作为json对象发送）。 它有2个参数-电子邮件和密码。 请求正文看起来像

{
   "email": "test@test.com",
   "password": "test"
}

这是大张旗鼓的YAML

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

这是包含请求参数的参考架构（ /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

这是在招摇的用户界面中的外观 如您在图像上看到的，请求的主体为空（而我有2个参数），这就是问题所在。 如果我将标题从application/json更改为application/x-www-form-urlencoded那么它将起作用（它将在参数列表中显示所有参数）。 如何使其在该列表中显示json对象参数？

Answer 1

您的规格正确，并且在Swagger UI中显示的结果正确，并且完全符合OpenAPI 3.0定义的预期。

请注意，有两个部分，“参数”（用于parameters ）和“请求正文”（用于requestBody ）。 在OpenAPI 3.0中， parameters仅用于查询参数，路径参数，请求标头和cookie； 而requestBody显示在“请求正文”部分。 您可以单击“模型”链接以查看带有属性描述的请求主体架构。