We have a flask api, and I am writing the docstrings for the classes. Each get method has url parameters in the form of url/?key=value, like for instance /?format=csv, When writing the docstrings, what is the best/recommended way of documenting them? My first idea was to put them in the method docstring, but pycharm and pylint complain as they are not actual arguments of the method.
Thanks
When it comes to documenting APIs there are various approaches. One widely adopted documentation solution is Swagger.
To document Flask project with Swagger there is a library called flasgger
With this library, you can put API documentation directly in Docstrings: source
import random
from flask import Flask, jsonify, request
from flasgger import Swagger
app = Flask(__name__)
Swagger(app)
@app.route('/api/<string:language>/', methods=['GET'])
def index(language):
"""
This is the language awesomeness API
Call this api passing a language name and get back its features
---
tags:
- Awesomeness Language API
parameters:
- name: language
in: path
type: string
required: true
description: The language name
- name: size
in: query
type: integer
description: size of awesomeness
responses:
500:
description: Error The language is not awesome!
200:
description: A language with its awesomeness
schema:
id: awesome
properties:
language:
type: string
description: The language name
default: Lua
features:
type: array
description: The awesomeness list
items:
type: string
default: ["perfect", "simple", "lovely"]
"""
language = language.lower().strip()
features = [
"awesome", "great", "dynamic",
"simple", "powerful", "amazing",
"perfect", "beauty", "lovely"
]
size = int(request.args.get('size', 1))
if language in ['php', 'vb', 'visualbasic', 'actionscript']:
return "An error occurred, invalid language for awesomeness", 500
return jsonify(
language=language,
features=random.sample(features, size)
)
app.run(debug=True)
If you do not want to document your parameters in doc strings you can also specify them in separate YML files. That is also described here
