使用 Flask-apidoc 自动生成 Api 文档

Flask-apidoc

影响我写文档的原因可能是代码和文档分离，有时候写完代码会忘记补文档，而且不能及时查看，使用 Flask-apidoc 可以解决我的问题，这个插件可以根据代码注释生成文档静态页面，静态文件可以放在项目中或者直接用nginx部署。

安装

1.安装 node.js

sudo apt-get install nodejs
sudo apt install nodejs-legacy
sudo apt install npm

2.安装 apidoc

npm install apidoc -g

3.Flask扩展包安装

pip install flask-apidoc

4.添加扩展包到Flask项目

依赖环境：

flask>=0.10.1
flask_script>=2.0.5

manage.py项目启动脚本配置

from views import app
from flask_apidoc.commands import GenerateApiDoc
from flask_script import Managermanager = Manager(app)
manager.add_command('apidoc', GenerateApiDoc())if __name__ == "__main__":manager.run()

视图函数文档注释说明示例

# -*- coding: utf-8 -*-
from flask import Flask
from flask_apidoc import ApiDocapp = Flask(__name__)
doc = ApiDoc(app=app)@app.route('/users', methods=['POST'])
def register():"""@api {post} /api/v1.0/users 注册@apiVersion 1.0.0@apiName register_user@apiGroup Users@apiParam {String}  mobile      (必须)    用户手机号@apiParam {String}  password    (必须)    用户密码@apiParam {String}  sms_code    (必须)    用户短信验证码@apiParamExample {json} Request-Example:{mobile: "13970512239",password: "123456",sms_code: "907896"}@apiSuccess (回参) {int} user_id  用户注册id@apiSuccess (回参) {String} name  用户昵称@apiSuccess (回参) {String} mobile  用户注册手机号@apiSuccess (回参) {String} avatar  用户头像地址@apiSuccess (回参) {String} create_time  用户创建时间@apiSuccessExample {json} Success-Response:{"errno":0,"errmsg":"注册成功！","data": {"user_id": 1,"name": "lynnyq","mobile": "13813888888","avatar": "http://p3ifu3dwc.bkt.clouddn.com/FjuAwxmcCtiud_nOZ","create_time": "2010-1-1 12:12:12"}}@apiErrorExample {json} Error-Response:{"errno":4001,"errmsg":"数据库查询错误！"}"""pass

生成接口文档命令

执行python manager.py apidoc生成文档，如果这个命令报错或者没反应的话，可以使用下面这个：
apidoc -o static/docs（亲测有效）
或者apidoc -o static/docs --debug显示调试信息

*注：有人总结说，要给需要生成文档的代码文件头部增加文档字符串才行。如果文档字符串没有或者为空字符串的话，apidoc不起效。

接口文档页面效果示例

注释中的@apiGroup可以用来给文档分组

使用 Flask-apidoc 自动生成 Api 文档相关推荐

springboot 集成 swagger 自动生成API文档
Swagger是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的Web服务.简单来说,Swagger是一个功能强大的接口管理工具,并且提供了多种编程语言的前后端分离解决方案. S ...
【接口文档】Django restful framework中自动生成API文档
Django restful framework中自动生成API文档一.Swagger概述 1.引言当接口开发完成,紧接着需要编写接口文档.传统的接口文档使用Word编写,or一些接口文档管理平台 ...
swagger php修改成中文,PHP使用swagger自动生成API文档
使用 swagger 自动生成 API 文档使用 swagger 自动生成 API 文档,有需要的朋友可以参考下. 一.下载 swagger-ui 直接上传服务器二.下载 swagger-php ...
SpringBoot 自动生成API文档
SpringBoot 自动生成API文档在做项目的时候,如果项目是前后分离的,后端一定要和前端或者是移动端对接接口,那么问题来了,接口是不是要自己写给他们看,一般的会采用Excel或者Word来写, ...
超详细！使用swagger自动生成Api文档（swagger-ui）
介绍 swagger是什么? swagger-ui 使用swagger-ui 简单使用 swagger api注解本文参考: 介绍这里是一些介绍,如果想直接看如何使用,请直接跳过这部分.但如果有时 ...
java apidoc案例_java 自动生成api 文档：apidoc
官网:apidocjs 首先声明下,apidoc是基于注释来生成文档的,它不基于任何框架,而且支持大多数编程语言,适用于java项目.跟已有的项目框架没有任何关系一.apidoc简介 apidoc通 ...
windows api中文文档_Web服务开发：Spring集成Swagger，3步自动生成API文档
目录: 1,Spring Boot集成Swagger 2,Swagger接口文档页面 3,常见问题和解决方法在Sping开发REST接口服务时,API文档是不可缺少的一个重要部分.Swagger框架 ...
swagger 修改dto注解_Web服务开发：Spring集成Swagger，3步自动生成API文档
目录: 1,Spring Boot集成Swagger 2,Swagger接口文档页面 3,常见问题和解决方法在Sping开发REST接口服务时,API文档是不可缺少的一个重要部分.Swagger框架 ...
PHP使用swagger-php自动生成api文档（详细附上完整例子）
thinkphp5结合swagger自动生成接口文档整体介绍 swagger-php.swagger-ui.swagger-editor swagger-ui:主要就是放到tp项目public目录下 ...
如何利用showdoc自动生成API文档
介绍 showdoc是一个适合IT团队的文档工具,阅读本文前需要对showdoc有基本了解 .基本介绍可看:https://www.showdoc.cc/help 对于写API文档这件事,虽然说文本编 ...

使用 Flask-apidoc 自动生成 Api 文档

Flask-apidoc

安装

生成接口文档命令

接口文档页面效果示例

使用 Flask-apidoc 自动生成 Api 文档相关推荐

最新文章

热门文章