如何为 url 参数编写文档字符串
How to write docstring for url parameters
我们有一个烧瓶 api,我正在为 类 编写文档字符串。
每个get方法都有url参数,形式为url/?key=value,比如/?format=csv,写docstrings时,best/recommended记录方式是什么他们?
我的第一个想法是将它们放在方法文档字符串中,但是 pycharm 和 pylint 抱怨说它们不是方法的实际参数。
谢谢
在记录 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
我们有一个烧瓶 api,我正在为 类 编写文档字符串。 每个get方法都有url参数,形式为url/?key=value,比如/?format=csv,写docstrings时,best/recommended记录方式是什么他们? 我的第一个想法是将它们放在方法文档字符串中,但是 pycharm 和 pylint 抱怨说它们不是方法的实际参数。
谢谢
在记录 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