用 swagger 发布一个 json body

问题描述

我想用 Swagger 发布一个 json 正文，如下所示:

I would like to POST a json body with Swagger, like this :

curl -H "Content-Type: application/json" -X POST -d {"username":"foobar","password":"xxxxxxxxxxxxxxxxx", "email": "[email protected]"}' http://localhost/user/register

目前，我有这个定义:

"/auth/register": {
        "post": {
            "tags": [
              "auth"
            ],
            "summary": "Create a new user account",
            "parameters": [
                {
                    "name": "username",
                    "in": "query",
                    "description": "The username of the user",
                    "required": true,
                    "type": "string"
                },
                {
                    "name": "password",
                    "in": "query",
                    "description": "The password of the user",
                    "required": true,
                    "type": "string",
                    "format": "password"
                },
                {
                    "name": "email",
                    "in": "query",
                    "description": "The email of the user",
                    "required": true,
                    "type": "string",
                    "format": "email"
                }
            ],
            "responses": {
                "201": {
                    "description": "The user account has been created",
                    "schema": {
                        "$ref": "#/definitions/User"
                    }
                },
                "default": {
                    "description": "Unexpected error",
                    "schema": {
                        "$ref": "#/definitions/Errors"
                    }
                }
            }
        }
    }

但是数据是在 URL 中发送的.这里生成的卷曲由 Swagger 提供:

But the data are sent in the URL. Here the generated curl provided by Swagger :

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' 'http://localhost/user/register?username=foobar&password=password&email=foo%40bar.com'

我知道 query 键工作不好，但我没有找到 POST JSON 正文的方法.我试过 formData 但没有用.

I understand that the query keywork is not good, but I didn't find the way to POST a JSON body. I tried formData but it didn't work.

推荐答案

需要使用body参数:

    "parameters": [
      {
        "in": "body",
        "name": "body",
        "description": "Pet object that needs to be added to the store",
        "required": false,
        "schema": {
          "$ref": "#/definitions/Pet"
        }
      }
    ],

和#/definitions/Pet被定义为一个模型:

"Pet": {
  "required": [
    "name",
    "photoUrls"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64"
    },
    "category": {
      "$ref": "#/definitions/Category"
    },
    "name": {
      "type": "string",
      "example": "doggie"
    },
    "photoUrls": {
      "type": "array",
      "xml": {
        "name": "photoUrl",
        "wrapped": true
      },
      "items": {
        "type": "string"
      }
    },
    "tags": {
      "type": "array",
      "xml": {
        "name": "tag",
        "wrapped": true
      },
      "items": {
        "$ref": "#/definitions/Tag"
      }
    },
    "status": {
      "type": "string",
      "description": "pet status in the store",
      "enum": [
        "available",
        "pending",
        "sold"
      ]
    }
  },
  "xml": {
    "name": "Pet"
  }
},

参考:https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/test/resources/2_0/petstore.json#L35-L43

OpenAPI/Swagger v2 规范:https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameter-object

OpenAPI/Swagger v2 spec: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameter-object

对于 OpenAPI v3 规范，body 参数已被弃用.要定义 HTTP 负载，需要使用 requestBody 代替，例如https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/test/resources/3_0/petstore.json#L39-L41

For OpenAPI v3 spec, body parameter has been deprecated. To define the HTTP payload, one needs to use the requestBody instead, e.g. https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/test/resources/3_0/petstore.json#L39-L41

OpenAPI v3 规范:https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#requestBodyObject

OpenAPI v3 spec: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#requestBodyObject

这篇关于用 swagger 发布一个 json body的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！