Swagger POST Json Body 参数架构 YAML

Question

我正在使用 swagger-api 和 swagger-editor 作为路线的 RESTful API。我不明白为什么我通过 body 发送的 JSON 从未到达我的控制器。这是我的 YAML

  schemes:
  - http
  - https

produces: [application/json, multipart/form-data, application/x-www-form-urlencoded]

paths:
 /projects:
    x-swagger-router-controller: project
    post:
      description: create a new project
      operationId: postProjects
      consumes:
        - application/json
      parameters:
        - name: param1
          in: body
          description: description
          required: false
          schema:
            $ref: "#/definitions/Project" 
      responses:
        "200":
          description: Success
          schema:
            $ref: "#/definitions/Project" 
        default:
          description: Error
          schema: 
            $ref: "#/definitions/ErrorResponse"

definitions:
  Project:
    properties:
      name:
       type: string
    required:
      - name

我发送的 post 请求示例。

curl -v -X POST -H "Content-Type: application/json" -d '{"name":"test"}' http://127.0.0.1:10010/projects

和响应

{"message":"Request validation failed: Parameter (param1) failed schema validation","code":"SCHEMA_VALIDATION_FAILED","failedValidation":true,"results":{"errors":[{"code":"OBJECT_MISSING_REQUIRED_PROPERTY","message":"Missing required property: name","path":[]}],"warnings":[]},"path":["paths","/projects","post","parameters","0"],"paramName":"param1"}

如果我将参数 "name" 设置为不需要，我只会收到这样的空响应 { 参数 1: { 路径: [ 'paths', '/projects', 'post', 'parameters', '0' ], 模式： { 姓名：'param1', 在：'body'，描述：'description'，要求：假，架构：[Object]}，原始值：{}，价值： {} } } 我不知道为什么其他格式（例如 header、路径或表单数据可以正常工作。我总是收到一个空 object。 req.swagger.params 没有价值。我尝试了几种模式，但即使是最简单的模式也不起作用。我可以从 header 中看出 'content-type'：'application/json'。因此设置了内容类型，模式验证名为 "name" 的简单字符串参数。一切都应该没问题。但仍然没有。

Answer 1

此问题已修复。这与招摇无关。我用 nodeJs 构建了一个 API，我意识到我没有中间件来处理 body 参数。所以因为我在启用 swagger 中间件之前错过了一步，所以我无法对 body 参数做任何事情。

Answer 2

将 json 数据发送到 API 后端时得到空值的主要原因是大多数时候你给出的参数路径和你给参数的命名。

您还必须明确声明您期望的架构类型

您必须将参数名称设置为 body 并设置 in: body 以便它选择正文对象作为 JSON

这里有一个例子。你可以试试看

/auth/register:
    post:
      tags:
        - Auth
      parameters:
        - in: body
          name: user
          description: Create a new user.
          schema:
            type: object
            required:
              - firstName
              - lastName
              - email
              - password
              - confirmPassword
            properties:
              firstName:
                type: string
              lastName:
                type: string
              email:
                type: string
              password:
                type: string
              confirmPassword:
                type: string
            example:
              firstName: Jane
              lastName: Doe
              email: janedoe@gmail.com
              password: pass
              confirmPassword: pass
      responses:
        "200":
          description: OK

Swagger POST Json Body 参数架构 YAML

Swagger POST Json Body Parameter Schema YAML

json

post

yaml

swagger

swagger-editor