flasgger useage maybe

README.md

install flask and flasgger using:

pip install flask
pip install flasgger

then run flask with:

export FLASK_APP=api
export FLASK_ENV=development
flask run

documentation lives in : 127.0.0.1:5000/apidocs/

api.py

from flask import Flask, jsonify, request
from flasgger import Swagger, swag_from

app = Flask(__name__)
swagger = Swagger(app)


@app.route("/")
@swag_from('index.yml')
def say_hi():
    return jsonify({"result": "hi there"}), 200


@app.route("/", methods=['POST'])
def get_something():
    """
    file: get_something.yml
    """
    if request.json.get("tst_data"):
        return jsonify({"result": "inserted!"}), 201
    return jsonify({"result": "failed"}), 400


@app.route("/<int:id>/", methods=['DELETE'])
@swag_from("remove_something.yml")
def remove_something(id):
    """remove something route

    this is the test for this route with a normal docstring. one would
    be able to use the `file:` thing to be able to include the given
    documentation in the file.
    
    :param int: id of the object to be removed    
    """
    if id == 10:
        return jsonify({"result": "removed!"}), 202
    return jsonify({"result": "failed"}), 204

get_something

Get something and insert it
This route will receive some data and will insert it.
---
parameters:
  - name: tst_data
    description: the header we want to be present
    in: body
    type: string
    required: true
responses:
  201:
    description: inserted successfully
    examples:
      {"result": "inserted!"}
  400:
    description: missed some headers
    examples:
      {"result": "failed"}

index.yml

Index page
this is the index page which will say hi only:)
---
responses:
  200:
    description: a dict object containing a `hi_there` value in there
    

remove_something.yml

Remove something
this will receive an id and will try to remove it
---
parameters:
  - name: id
    description: the id of the object we want to remove
    in: path
    type: int
    path: /id/
    required: true
responses:
  202:
    description: succesful remove
    examples:
      {"result": "removed!"}
  204:
    description: object could not be found to remove
    examples:
      {"result": "failed"}