如何修复从openapi代码生成器获得的验证错误，该API使用的是应用程序/x表单-urlencoded内容类型？

Question

我遵循了open指南提到的这里来定义一个api，它使用了应用程序/x-www-form-urlencoded，并编写在API下面：

{
    "openapi": "3.0.0",
    "info": {
        "version": "1.0.draft",
        "title": "user management api",
        "description": "This document defines interface to user management"
    },
    "servers": [{
        "url": "{apiRoot}/test",
        "variables": {
            "apiRoot": {
                "default": "https://example.com"
            }
        }
    }],
    "paths": {
        "/users/resetpassword": {
            "post": {
                "summary": "reset password of a user",
                "operationId": "resetUserPassword",
                "parameters": [{
                        "name": "username",
                        "in": "formData",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "password",
                        "in": "formData",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "204": {
                        "description": "User password has been changed"
                    }
                }
            }
        }
    }
}

运行下面的命令，使用码发生器从上面打开的API文档生成go代码。

docker run --rm -v ${PWD}:<file_path> openapitools/openapi-generator-cli generate -i <file_path> --skip-validate-spec -g go-server -o <file_out_path>

获得以下错误：

-attribute paths.'/users/resetpassword'(post).parameters.[username].in is not of type `string`
-attribute paths.'/users/resetpassword'(post).parameters.[password].in is not of type `string`

如何纠正上述错误？

Answer 1

您混淆了OpenAPI 2.0和OpenAPI 3.0语法。

在OpenAPI 3.0中，请求体(包括表单数据)是使用requestBody关键字定义的。将parameters部分替换为：

"requestBody": {
  "required": true,
  "content": {
    "application/x-www-form-urlencoded": {
      "schema": {
        "type": "object",
        "required": [
          "username",
          "password"
        ],
        "properties": {
          "username": {
            "type": "string"
          },
          "password": {
            "type": "string"
          }
        }
      }
    }
  }
}

YAML版本：

requestBody:
  required: true
  content:
    application/x-www-form-urlencoded:
      schema:
        type: object
        required:
        - username
        - password
        properties:
          username:
            type: string
          password:
            type: string