Syntax for HTTP methods in same def using Swagger

Question

I am new to SwaggerUI. In my python code, I have an API called 'work' which supports POST, PUT and DELETE HTTP methods.

Now I want to create Swagger Documentation for the same. I am using the following code:

@app.route('/work', methods=['POST', 'PUT', 'DELETE'])
def work():
"""
    Micro Service Based API for work operations
    This API is for work to task matching operations
    ---
    paths:
      /cv:
        put:
          parameters:
            - name: body
              in: body
              required: true
              schema:
                id: data
                properties:
                    _id:
                        type: string
              description: Id
          responses:
                    200:
                        description: Please wait the calculation, you'll receive an email with results
        delete:
          parameters:
            - name: body
              in: body
              required: true
              schema:
                id: data
                properties:
                    _id:
                        type: string
              description: Id
          responses:
                    200:
                        description: Please wait the calculation, you'll receive an email with results
        post:
          responses:
                    200:
                        description: done
"""

However, it does not seem to work.

I tried browsing the following Documentation link but not to much help https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#pathsObject

Could you please help me out?

The parameters each of the HTTP methods request is different and I wish to also specify a different description for each method in my HTTP UI.

EDITS

Added this to index.yml file.

swagger: "2.0"
info:
  description: "This is a sample server Petstore server.  You can find out more about     Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).      For this sample, you can use the api key `special-key` to test the authorization     filters."
  version: "1.0.0"
  title: "Swagger Petstore"
  schemes:
- "http"
paths:
  /work:
    put:
      tags:
  - "WORK"
  summary: "Update a Work Score"
  description: ""
  consumes:
  - "application/json"
  parameters:
  - in: "body"
    name: "body"
    description: "Work ID whose score needs to be updates"
    required: true
    schema:
      $ref: "#/definitions/Data"
  responses:
    200:
      description: "Invalid input"
  /scoreCompute:
    post:
  tags:
  - "ABCD"
  summary: "Compute ABCD"
  description: ""
  consumes:
  - "application/json"
  parameters:
  - in: "body"
    name: "body"
    description: "Compute ABCD"
    required: true
    schema:
      $ref: "#/definitions/TaskId"
  responses:
    200:
      description: "Invalid input"
definitions:
  Data:
type: object
properties:
  _id:
    type: string
    description: Enter ID
  TaskId:
type: object
properties:
  job_id:
    type: string
    description: Enter ID

Made the above changes to python code.

@app.route('/work', methods=['POST', 'PUT', 'DELETE'])
@swag_from('index.yml')
def work():

However http://127.0.0.1:5000/apidocs/#!/default/ shows nothing at all.

Answer 1

If you are using Flasgger (http://github.com/rochacbruno/flasgger) Sadly it does not support defining different HTTP methods in the same docstring yet, there is this issue opened.

However, there is a workaround to make it working.

1) Put your YAML in a separate file
2) Load it from Swagger template_file

YAML FILE, saves as test.yaml:

definitions:
  Data:
    type: object
    properties:
      _id:
        type: string

paths:
  /cv:
    put:
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/Data'
      responses:
        200:
          description: |
            Please wait the calculation, you'll receive an email with results
    delete:
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/Data'
      responses:
        200:
          description: |
            Please wait the calculation, you'll receive an email with results
    post:
      responses:
        200:
          description: done

and then test.py

from flask import Flask
from flasgger import Swagger


app = Flask(__name__)
Swagger(app, template_file='test.yaml')


@app.route('/cv', methods=['POST', 'PUT', 'DELETE'])
def cv():
    """
    Micro Service Based API for CV operations
    This API is for job to CVs matching operations
    """


app.run(debug=True)

And you get