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

Question

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

{
   "email": "[e-mail]",
   "password": "test"
}

这是大摇大摆的 YAML

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

这里是包含请求参数的参考模式(< code >/components/schemas/sign up )

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

Answer 1

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

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