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

Question

我正在用 OpenAPI 版本 3 大摇大摆地为 Web API 编写文档。我使用 swagger php package 从注释中生成文档化的 json。我有服务，我发送 post 添加新用户的请求，请求的 body 是 json（因此参数发送为 json object）。它有 2 个参数 - 电子邮件和密码。请求 body 看起来像

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

这是 swagger 的 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

这是它招摇的样子 UI 正如您在图片上看到的，请求的 body 为空（而我有 2 个参数），这就是问题所在。如果我将 header 从 application/json 更改为 application/x-www-form-urlencoded 那么它将起作用（它将在参数列表中显示所有参数）。如何让它在该列表中显示 json object 参数？

Answer 1

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

注意有两个部分，"Parameters"（parameters）和"Request body"（requestBody）。在 OpenAPI 3.0 中，parameters 仅用于查询参数、路径参数、请求头和 cookie；而 requestBody 显示在 "Request body" 部分中。您可以单击 "Model" link 查看带有属性描述的请求正文架构。

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

Display json object properties in parameters list in Swagger UI

php

json

swagger

swagger-ui