flask后端项目接口文档的管理问题-flasgger
接口文档的管理问题
有一个现实的问题，就是接口文档的管理问题，
Flask 是一个以自由度高、灵活性强著称的 Python Web 框架。但高灵活性也意味着无尽的代码维护成本、高自由度意味着代码质量更依赖程序员自身而没有一致的标准和规范。因此团队内开发时 Flask 项目更需要建立代码和文档规范以保证不会出现太大的偏差。
本文从 Api 的角度探究 Flask 项目的 Api 规范以及获得 Api 文档的最佳姿势。众数周知，文档的编写和整理工作将花费巨大精力甚至不亚于代码的编写，因此在时间紧任务重的情况下，文档是首先被忽略的工作。不过，就算项目在初期存在文档，但在后面的迭代中，文档落后严重，其产生的误导比没有文档更加可怕。
因此，个人认为 文档随代码走，代码改动时文档也应该跟进变动，但本着 人是不可靠的 原则，文档理想上是应该由代码生成，而不是靠人工维护。如果代码有任何改动，文档也能自动更新，这将是一件非常优雅的事情。
接口文档是一个短期看不会有什么收益，但是长期坚持会有收益的事情，会产生复利的效应，
swagger
看看网上的说法1
Swagger 有什么用？ Swagger 有以下 3 个重要的作用：
1，将项目中所有的接口展现在页面上，这样后端程序员就不需要专门为前端使用者编写专门的接口文档；
2，当接口更新之后，只需要修改代码中的 Swagger 描述就可以实时生成新的接口文档了，从而规避了接口文档老旧不能使用的问题；
3，通过 Swagger 页面，我们可以直接进行接口调用，降低了项目开发阶段的调试成本。
看看网上的说法2
Swagger号称是最好的Rest Api 文件生成工具，但是作为一个一直从事java相关开发工作的开发者。在2018年6月以前一直坚持用Markdown来手写接口文档，即便是那时候有同事给我推荐过，但作为一个骨子里追求极简的程序员，我一直没有想明白一个需要写一大堆注解强侵入到后端代码工具，它为什么会在中国如此风靡，被很多的java后端应用开发者集成到自己的中。在国内的百度上搜索Swagger相关的博客数量惊人。
看看网上的说法3
Swagger? 不好用
最近用了一下swagger，swagger是一个用于把代码和文档连接起来的工具，我们在注释里写好一些东西，然后swagger生成出一个网页， 这样可以方便的在网页上点一下测试，就可以发出一个请求。但是，实际体验中，并不好用，原因如下：
文档虽然可以自动生成，但是书写相当繁琐
虽然可以在网页上自动生成一个用例用于测试，但是参数意义、是否可选等不明确
功能
API 文档：说明了 Api 接口的基本信息，请求信息，返回信息
API调试：类似 postman,自动填充参数类型和返回信息，能做基础参数验证。较之 postman 用户体验更佳
验证参数格式类型，校验更加严谨
使用 Swagger 的目的优点：
先说优点吧，毕竟这工具确实提升了不少工作效率。
1 节省了大量手写接口文档的时间，这是最大的优势
2 生成的接口文档(参考上图)可以直接在线测试，省去了使用 Postman 设置接口参数的过程，而且请求参数，返回参数一目了然，提升API的质量，方便开发进行自测
3 接口按照模块已经分类好了，很清晰
Swagger 痛点缺点：
严谨的规范给工程师带来不适，简单的接口或许会花费更多的时间来维护 swagger
这都是利弊的选择，
我是一定要进行接口文档的维护的，这是作为一个专业程序员的要求，
我还是选择使用swagger
1，接口文档跟着项目代码走，这个比较好维护
2，这是一个在线的文档，比较好查看，而且可以快速调试，
当下支持 Flask 和 Swagger 的工具大概如下：
flask-swagger
flasgger
flask-restplus
综合比较了一下，flask-restplus 对框架入侵较大， flask-swagger 集成 Swagger-UI比较繁琐，故尝试使用 flasgger。
flasgger的使用
安装
使用pip命令，pip install flasgger
https://github.com/flasgger/flasgger/blob/master/README.zh.md
这是flasgger的官方文档
第一种使用方式：直接写在代码中，
from flask import Flask
from flasgger import Swagger
from flask_restful import Api, Resource
app = Flask(__name__)
api = Api(app)
swagger = Swagger(app)
class Username(Resource):
def get(self, username):
"""
This examples uses FlaskRESTful Resource
It works also with swag_from, schemas and spec_dict
---
parameters:
- in: path
name: username
type: string
required: true
responses:
200:
description: A single user item
schema:
id: User
properties:
username:
type: string
description: The name of the user
default: Steven Wilson
"""
return {'username': username}, 200
api.add_resource(Username, '/username/<username>')
app.run(debug=True)
第二种使用方式：使用yaml文件
也可以以独立文件 yaml文件形式引入脚本中
import random
from flask import Flask, jsonify, request
from flasgger import Swagger
from flasgger.utils import swag_from
app = 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", 500
return jsonify(
language=language,
features=random.sample(features, size)
)
app.run(debug=True)
flasgger的yaml文件解析：
在flasgger的配置文件中，以yaml的格式描述了flasgger页面的内容；
tags标签
tags标签可以用作接口分组，分类，
parameters标签
parameters标签中可以放置这个api所需的参数，如果是GET方法，可以放置url中附带的请求参数，如果是POST方法，可以将参数放置在schema子标签下面；
in: path
in: body
in: formData
type: integer
responses标签
responses标签中可以放置返回的信息，以状态码的形式分别列出，每个状态码下可以用schema标签放置返回实体的格式；
flasgger的不足
flasgger的配置文件中，对于POST方法，在描述POST body的schema标签中，不支持以yaml格式描述的数组或嵌套的object，这使得页面上面无法显示这类POST body的example；
解决方案：将这类POST body的example放置在description部分（三横杠”—“上面的部分），由于description部分是用html格式解析的，所以可以以html的语法编写；
总结
Swagger的写法是直接在接口上添加注释、在对象和对象的参数上添加注释。有很多人认为这样非常鸡肋，耦合度太高，或是认为需要写较多的注释太过繁琐。
博主认为和代码结合在这恰恰是它的优点，让你每次修改接口时不需要浪费时间去找到你的文档，亦或是忘记了修改文档。而所谓过多的注释，我想这应该比写word要快的多，当然比不过口头传达了。
===
我还是喜欢
用postman调试接口
用markdown编写接口文档，
