如何为 url 参数编写文档字符串

Question

我们有一个烧瓶 api，我正在为这些类编写文档字符串。 每个 get 方法都有 url/?key=value 形式的 url 参数，例如 /?format=csv，在编写文档字符串时，记录它们的最佳/推荐方式是什么？ 我的第一个想法是将它们放在方法文档字符串中，但是 pycharm 和 pylint 抱怨，因为它们不是方法的实际参数。

谢谢

Answer 1

在记录 API 时，有多种方法。一种广泛采用的文档解决方案是 Swagger。

要使用 Swagger 记录 Flask 项目，有一个名为的库 flasgger

有了这个库，你可以直接把API文档放到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)

如果您不想在文档字符串中记录您的参数，您也可以在单独的 YML 文件中指定它们。这也被描述为here