python--Flasgger使用心得

本文主要是介绍python--Flasgger使用心得，希望对大家解决编程问题提供一定的参考价值，需要的开发者们随着小编来一起学习吧！

转载:https://changsiyuan.github.io/2017/05/20/2017-5-20-flasgger/

引言

Flask是一款流行的Python实现的Web开发微框架；
Swagger是一款Restful接口的文档在线自动生成+功能测试功能软件；
通过swagger能够清晰、便捷地调试符合Restful规范的API；
在flask框架中使用的swagger即为flasgger，flasgger是flask支持的swagger UI，便于调试使用flask框架搭建的web api接口；

本文介绍了flasgger的用法和不足之处。

使用方法

首先，需要在项目中安装flasgger，具体方法有两种：

方法一：在visual studio中右键工程，搜索flasgger，自动安装；
方法二：使用pip命令，pip install flasgger；

安装后，使用下面的程序框架，搭建最简单的web api：

app = Flask(__name__)
Swagger(app)@app.route('/api/<string:language>/', methods=['GET'])
def index(language):"""This is the language awesomeness APICall this api passing a language name and get back its features---tags:- Awesomeness Language APIparameters:- name: languagein: pathtype: stringrequired: truedescription: The language name- name: sizein: querytype: integerdescription: size of awesomenessresponses:500:description: Error The language is not awesome!200:description: A language with its awesomenessschema:id: awesomeproperties:language:type: stringdescription: The language namedefault: Luafeatures:type: arraydescription: The awesomeness listitems:type: stringdefault: ["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", 500return jsonify(language=language,features=random.sample(features, size))app.run(debug=True)

从上面的程序我们可以看出，只要将yaml格式的flasgger描述性程序放置在两组双引号之间的位置，即可实现flasgger的基本功能；

访问http://localhost:5000/apidocs/index.html 即可看到flasgger页面

当然，上面的yaml描述性程序可以放置在单独的文件中，那么api中用@符号引入这个文件即可：

import random
from flask import Flask, jsonify, request
from flasgger import Swagger
from flasgger.utils import swag_fromapp = Flask(__name__)
Swagger(app)@app.route('/api/<string:language>/', methods=['GET'])
@swag_from('index.yml')
def index(language):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", 500return jsonify(language=language,features=random.sample(features, size))app.run(debug=True)

flasgger配置文件解析：

在flasgger的配置文件中，以yaml的格式描述了flasgger页面的内容；
tags标签中可以放置对这个api的描述和说明；
parameters标签中可以放置这个api所需的参数，如果是GET方法，可以放置url中附带的请求参数，如果是POST方法，可以将参数放置在schema子标签下面；
responses标签中可以放置返回的信息，以状态码的形式分别列出，每个状态码下可以用schema标签放置返回实体的格式；

flasgger的不足

flasgger的配置文件中，对于POST方法，在描述POST body的schema标签中，不支持以yaml格式描述的数组或嵌套的object，这使得页面上面无法显示这类POST body的example；
解决方案：将这类POST body的example放置在description部分（三横杠”—“上面的部分），由于description部分是用html格式解析的，所以可以以html的语法编写；