Add support for specific docs for each method of an endpoint

[alejoar]

This is a quick take on #30

This pull request allows to specify different documentation for each method of the same endpoint without breaking the current syntax.

Here's a working example where both the current (/current_style endpoint) and the proposed (/user endpoint) syntax are used at the same time:

@app.route('/user', methods=["GET", "PUT"])
def user():
    """
    get:
        Get a user
        Use this endpoint to get a user object
        ---
        tags:
            - User API
        definitions:
          - schema:
                id: User
                properties:
                    name:
                        type: string
                        description: the user's name
                    age:
                        type: integer
                        description: the user's age
        responses:
            200:
                description: user obtained
                schema:
                    $ref: "#/definitions/User"
    put:
        Update a user
        Use this endpoint to update a user
        ---
        tags:
            - User API
        parameters:
            - name: name
              in: formData
              type: string
              required: true
            - name: age
              in: formData
              type: integer
              required: true
        responses:
            202:
                description: user updated
                schema:
                    $ref: "#/definitions/User"
    """
    pass

@app.route('/current_style')
def current_style():
    """
    Create a new user
    ---
    tags:
      - users
    definitions:
      - schema:
          id: Group
          properties:
            name:
             type: string
             description: the group's name
    parameters:
      - in: body
        name: body
        schema:
          id: User
          required:
            - email
            - name
          properties:
            email:
              type: string
              description: email for user
            name:
              type: string
              description: name for user
            address:
              description: address for user
              schema:
                id: Address
                properties:
                  street:
                    type: string
                  state:
                    type: string
                  country:
                    type: string
                  postalcode:
                    type: string
            groups:
              type: array
              description: list of groups
              items:
                $ref: "#/definitions/Group"
    responses:
      201:
        description: User created
    """
    pass

And here's the resulting json:

{
  "definitions": {
    "Address": {
      "properties": {
        "country": {
          "type": "string"
        }, 
        "postalcode": {
          "type": "string"
        }, 
        "state": {
          "type": "string"
        }, 
        "street": {
          "type": "string"
        }
      }
    }, 
    "Group": {
      "properties": {
        "name": {
          "description": "the group's name", 
          "type": "string"
        }
      }
    }, 
    "User": {
      "properties": {
        "age": {
          "description": "the user's age", 
          "type": "integer"
        }, 
        "name": {
          "description": "the user's name", 
          "type": "string"
        }
      }, 
      "required": [
        "email", 
        "name"
      ]
    }
  }, 
  "info": {
    "title": "Cool product name", 
    "version": "0.0.0"
  }, 
  "paths": {
    "/current_style": {
      "get": {
        "description": "", 
        "parameters": [
          {
            "in": "body", 
            "name": "body", 
            "schema": {
              "$ref": "#/definitions/User"
            }
          }
        ], 
        "responses": {
          "201": {
            "description": "User created"
          }
        }, 
        "summary": "Create a new user", 
        "tags": [
          "users"
        ]
      }
    }, 
    "/user": {
      "get": {
        "description": "Use this endpoint to get a user object", 
        "responses": {
          "200": {
            "description": "user obtained", 
            "schema": {
              "$ref": "#/definitions/User"
            }
          }
        }, 
        "summary": "Get a user", 
        "tags": [
          "User API"
        ]
      }, 
      "put": {
        "description": "Use this endpoint to update a user", 
        "parameters": [
          {
            "in": "formData", 
            "name": "name", 
            "required": true, 
            "type": "string"
          }, 
          {
            "in": "formData", 
            "name": "age", 
            "required": true, 
            "type": "integer"
          }
        ], 
        "responses": {
          "202": {
            "description": "user updated", 
            "schema": {
              "$ref": "#/definitions/User"
            }
          }
        }, 
        "summary": "Update an user", 
        "tags": [
          "User API"
        ]
      }
    }
  }, 
  "swagger": "2.0"
}

I am currently using this on our production project at work, although I'm aware it is pretty dirty.

Please criticize as needed.

[steinsag]

Any chance to get that merged?

[AndrewCharlesHay]

please?