url 매개 변수에 대한 docstring 작성 방법

Question

플라스크 API가 있으며 클래스에 대한 docstring을 작성하고 있습니다. 각 get 메소드에는 url /? key = value 형식의 url 매개 변수가 있습니다 (예 : /? format = csv). 문서화 문자열을 작성할 때 문서화 방법을 문서화하는 최선의 방법은 무엇입니까? 첫 번째 아이디어는 그들을 docstring 메서드에 넣는 것이지만 pycharm과 pylint는 메서드의 실제 인수가 아니므로 불평합니다.

감사합니다.

Answer 1

API를 문서화 할 때 다양한 접근 방식이 있습니다. 널리 채택 된 문서 솔루션 중 하나는 Swagger입니다.

당신은 문서화 문자열에 직접 API 문서를 넣을 수 있습니다,이 라이브러리와 flasgger

라는 라이브러리가 자신감과 플라스크 프로젝트를 문서화하려면 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