除了 HTTP GET 之外的任何东西的 Swagger 规范

Question

我正忙于了解 swagger.json 规范的工作原理（在我的例子中是 api.json）。在研究过程中，我可以找到许多关于如何处理 GET 请求的示例，但对于 POST 或其他任何内容都没有。我迫切需要实现 POST 部分，但我觉得我需要更好地理解这一点，而不是复制和粘贴代码并依靠反复试验来使其工作。 Swagger.io 网站上的内容对初学者不友好。有人可以解释下面的示例代码中发生了什么，尤其是在两种情况下的“get:”之后：

{
"swagger": "2.0",
"info": {
    "version": "v1",
    "title": "FoodTrucks",
"description": "An TryApp sample API App where you can find Food trucks."
},
"host": "microsoft-apiapp1fe6951749ff4b76b8cc9194bc29ba61.azurewebsites.net:443",
"schemes": ["http", "https"],
"basePath": "/api/data",
"paths": {
    "/foodtrucks": {
        "get": {
            "tags": ["FoodTrucks"],
            "operationId": "getFoodTrucks",
            "consumes": [],
            "produces": ["application/json",
            "text/json",
            "application/xml",
            "text/xml"],
            "responses": {
                "200": {
                    "description": "OK",
                    "schema": {
                        "type": "array",
                        "items": {
                            "$ref": "#/definitions/Restaurant"
                        }
                    }
                }
            },
            "deprecated": false
        }
    },
    "/foodtrucks/{id}": {
        "get": {
            "tags": ["FoodTrucks"],
            "operationId": "getFoodTruckDetails",
            "consumes": [],
            "produces": ["application/json",
            "text/json",
            "application/xml",
            "text/xml"],
            "parameters": [{
                "name": "id",
                "in": "path",
                "required": true,
                "type": "integer",
                "format": "int32"
            }],
            "responses": {
                "200": {
                    "description": "OK",
                    "schema": {
                        "type": "array",
                        "items": {
                            "$ref": "#/definitions/Restaurant"
                        }
                    }
                }
            },
            "deprecated": false
        }
    }
},
"definitions": {
    "Restaurant": {
        "type": "object",
        "properties": {
            "id": {
                "format": "int32",
                "type": "integer"
            },
            "name": {
                "type": "string"
            },
            "likes": {
                "format": "int32",
                "type": "integer"
            },
            "savory": {
                "type": "boolean"
            },
            "sweet": {
                "type": "boolean"
            },
            "vegetarian": {
                "type": "boolean"
            },
            "bookable": {
                "type": "boolean"
            },
            "city": {
                "type": "string"
            }
        }
    }
 }
}

请您也提供一个简单的 POST 示例。

Answer 1

Swagger 的 extended examples 包含 POST。这是一个逐块解释的示例：

"post": {
    "description": "Creates a new pet in the store.  Duplicates are allowed",

描述是对操作的友好解释，主要来自documentation。

    "operationId": "addPet",

OperationId 是操作的友好名称。必须是独一无二的。

    "produces": [
      "application/json"
    ],

Produces 是端点输出的 MIME 类型

    "parameters": [
      {
        "name": "pet",
        "in": "body",
        "description": "Pet to add to the store",
        "required": true,
        "schema": {
          "$ref": "#/definitions/NewPet"

架构引用 ($ref) 指的是“定义”块中的数据类型定义。请参阅this JSON 中的 NewPet 部分。

        }
      }
    ],

parameters block of the documentation 中最好地描述了参数。

    "responses": {
      "200": {
        "description": "pet response",
        "schema": {
          "$ref": "#/definitions/Pet"
        }
      },

同样，回复最好在response documentation中描述

      "default": {
        "description": "unexpected error",
        "schema": {
          "$ref": "#/definitions/ErrorModel"
        }
      }

默认是default response，如果没有其他返回。

    }
  }