How to write docstring for url parameters

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 randomfrom flask import Flask, jsonify, requestfrom flasgger import Swaggerapp = 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