Question

我正忙着理解swagger.json规范是如何工作的（在我的例子中是它的api.json）。在研究时，我可以找到很多关于如何处理GET请求的例子，但没有任何关于POST或其他的东西。我迫切需要实现POST部分，但我觉得我需要更好地理解这一点，而不是复制和粘贴代码，并依靠反复试验来使其工作。 Swagger.io网站上的内容不是初学者友好的。有人可以解释下面的示例代码中发生的事情，特别是在＆＃39; get：＆＃39;在这两种情况下：

{
"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）是指＆＃34;定义中的数据类型定义＆＃34;块。请参阅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。

    }
  }

除HTTP GET之外的任何其他的Swagger规范

1 个答案: