Swagger specification for anything other than HTTP GET

Question

I'm busy understanding how the swagger.json specification works (in my case it's api.json). While researching, I could find numerous examples of how to handle GET requests but nothing for POST or anything else. My immediate need is to implement the POST part but I feel like I need to understand this better instead of copying and pasting code and relying on trial and error to make it work. The content in the Swagger.io website is not beginner friendly. Can someone explain what is going on in the example code below, particularly after the 'get:' in both cases:

{
"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"
            }
        }
    }
 }
}

Please can you help with a simple POST example as well.

Answer 1

Swagger's extended examples include POSTs. Here is a sample with a block-by-block explanation:

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

Description is a friendly explanation for the operation taken mostly from the documentation.

    "operationId": "addPet",

OperationId is a friendly name for the operation. Must be unique.

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

Produces is the MIME type of the endpoint's output

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

Schema references ($ref) refers to the data type definition in the "definitions" block. Refer to the NewPet section in this JSON.

        }
      }
    ],

Parameters are best described in this parameters block of the documentation.

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

Likewise, responses are best described in the response documentation

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

Default is the default response if nothing else returns.

    }
  }