影响我写文档的原因可能是代码和文档分离,有时候写完代码会忘记补文档,而且不能及时查看,使用 Flask-Docs 可以解决我的问题,这个插件可以根据代码注释生成文档页面,代码注释改动文档可以及时更新,而且支持离线文档下载。

Flask-Docs
Flask Api 文档自动生成插件

特性
根据代码注释自动生成文档
支持 Flask-RESTful
支持离线 markdown 文档下载
安装
pip install Flask-Docs

使用
from flask import Flask
from flask_docs import ApiDoc

app = Flask(__name__)

# 本地加载
# app.config['API_DOC_CDN'] = False

# 禁用文档页面
# app.config['API_DOC_ENABLE'] = False

# 需要显示文档的 Api
app.config['API_DOC_MEMBER'] = ['api', 'platform']

# 需要排除的 RESTful Api 文档
app.config['RESTFUL_API_DOC_EXCLUDE'] = []

ApiDoc(app)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
如何书写 markdown 格式文档
@@@
在注释结尾用 “@@@” 包含 markdown 格式文档
@@@

查看文档页面
http://127.0.0.1/docs/api

Api demo
@api.route('/add_data', methods=['POST'])
def add_data():
"""Add some data

Add some data in this routing

Args:
pass

Returns:
pass
"""
return jsonify({'api': 'add data'})
1
2
3
4
5
6
7
8
9
10
11
12
13

@api.route('/del_data', methods=['POST'])
def del_data():
"""Del some data

@@@
#### args

| args | nullable | type | remark |
|--------|--------|--------|--------|
| title | false | string | blog title |
| name | true | string | person's name |

#### return
- ##### json
> {"msg": "success", "code": 200}
@@@
"""
return jsonify({'api': 'del data'})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

@platform.route('/get_something', methods=['GET'])
def get_something():
"""
@@@
#### example
```
import requests
url='http://127.0.0.1:5000/api/get_something'
try:
print requests.get(url).text
except:
pass
```
@@@
"""
return jsonify({'platform': 'get something'})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

完整代码
#!/usr/bin/env python
# -*- coding:utf-8 -*-

from flask import Flask, render_template, jsonify, Blueprint
from flask_docs import ApiDoc

app = Flask(__name__)

# Local loading
# app.config['API_DOC_CDN'] = False

# Disable document pages
# app.config['API_DOC_ENABLE'] = False

# Api Document needs to be displayed
app.config['API_DOC_MEMBER'] = ['api', 'platform']

ApiDoc(app)

api = Blueprint('api', __name__)
platform = Blueprint('platform', __name__)

@api.route('/add_data', methods=['POST'])
def add_data():
"""Add some data

Add some data in this routing

Args:
pass

Returns:
pass
"""
return jsonify({'api': 'add data'})

@api.route('/del_data', methods=['POST'])
def del_data():
"""Del some data

@@@
#### args

| args | nullable | type | remark |
|--------|--------|--------|--------|
| title | false | string | blog title |
| name | true | string | person's name |

#### return
- ##### json
> {"msg": "success", "code": 200}
@@@
"""
return jsonify({'api': 'del data'})

@platform.route('/get_something', methods=['GET'])
def get_something():
"""
@@@
#### example
```
import requests
url='http://127.0.0.1:5000/api/get_something'
try:
print requests.get(url).text
except:
pass
```
@@@
"""
return jsonify({'platform': 'get something'})

app.register_blueprint(api, url_prefix='/api')
app.register_blueprint(platform, url_prefix='/platform')

if __name__ == '__main__':
app.run(host='0.0.0.0', port=5000, debug=True)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
Flask-RESTful Api demo
from flask_restful import Resource, Api

class TodoList(Resource):
"""Manage todolist"""

def post(self):
"""Submission of data

Args:
pass

Returns:
pass

"""
return {'todos': 'post todolist'}

def get(self):
"""
@@@
#### args

| args | nullable | type | remark |
|--------|--------|--------|--------|
| id | false | int | todo id |

#### return
- ##### json
> {...}
@@@
"""
return {'todos': 'get todolist'}

restful_api.add_resource(TodoList, '/todolist')
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

完整代码
#!/usr/bin/env python
# -*- coding:utf-8 -*-

from flask import Flask
from flask_restful import Resource, Api
from flask_docs import ApiDoc

app = Flask(__name__)

# Local loading
# app.config['API_DOC_CDN'] = False

# Disable document pages
# app.config['API_DOC_ENABLE'] = False

# RESTful Api documents to be excluded
app.config['RESTFUL_API_DOC_EXCLUDE'] = []

restful_api = Api(app)
ApiDoc(app)

class TodoList(Resource):
"""Manage todolist"""

def post(self):
"""Submission of data

Args:
pass

Returns:
pass

"""
return {'todos': 'post todolist'}

def get(self):
"""
@@@
#### args

| args | nullable | type | remark |
|--------|--------|--------|--------|
| id | false | int | todo id |

#### return
- ##### json
> {...}
@@@
"""
return {'todos': 'get todolist'}

restful_api.add_resource(TodoList, '/todolist')

if __name__ == '__main__':
app.run(host='0.0.0.0', port=5000, debug=True)

使用 Flask-Docs 自动生成 Api 文档的更多相关文章

  1. go实践之swagger自动生成api文档

    文章目录 go实践之swagger自动生成api文档 1.安装需要用到的包 2.接口代码支持swagger 3. 生成swagger接口 go实践之swagger自动生成api文档 作为一个后端开发, ...

  2. Django restful framework中自动生成API文档

    自动生成api文档(不管是函数视图还是类视图都能显示) 1.安装rest_framework_swagger库 pip install django-rest-swagger 2.在项目下的 urls ...

  3. 【转】Django restful framework中自动生成API文档

    转自 https://www.cnblogs.com/sui776265233/p/11350434.html 自动生成api文档(不管是函数视图还是类视图都能显示) 1.安装rest_framewo ...

  4. 使用bee自动生成api文档

    beego中的bee工具可以方便的自动生成api文档,基于数据库字段,自动生成golang版基于beego的crud代码,方法如下: 1.进入到gopath目录的src下执行命令: bee api a ...

  5. 自动生成api文档

    vs2010代码注释自动生成api文档 最近做了一些接口,提供其他人调用,要写个api文档,可是我想代码注释已经写了说明,能不能直接把代码注释生成api?于是找到以下方法 环境:vs2010 先下载安 ...

  6. 试试使用 eolinker 扫描 GitLab 代码注释自动生成 API 文档?

    前言: 一般写完代码之后,还要将各类参数注解写入API文档,方便后续进行对接和测试,这个过程通常都很麻烦,如果有工具可以读取代码注释直接生成API文档的话,那会十分方便. 此前一直都是在使用eolin ...

  7. SpringBoot结合Swagger2自动生成api文档

    首先在pom.xml中添加如下依赖,其它web,lombok等依赖自行添加 <dependency> <groupId>io.springfox</groupId> ...

  8. Spring Boot 项目学习 (四) Spring Boot整合Swagger2自动生成API文档

    0 引言 在做服务端开发的时候,难免会涉及到API 接口文档的编写,可以经历过手写API 文档的过程,就会发现,一个自动生成API文档可以提高多少的效率. 以下列举几个手写API 文档的痛点: 文档需 ...

  9. springboot 集成 swagger 自动生成API文档

    Swagger是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的Web服务.简单来说,Swagger是一个功能强大的接口管理工具,并且提供了多种编程语言的前后端分离解决方案. S ...

  10. apiDoc自动生成api文档

    在自定生成api文档方面以前都是使用swagger.json结合swagger工具来生成文档,偶然发现了apidoc这个生成api的工具,发现使用起来比swagger更加简单,下面整理一下使用过程: ...

随机推荐

  1. jenkins+svn完整打包并上传到linux服务器上

    因为公司用的是svn版本管理工具并且部署在了windows服务器上,所以测试环使用jenkins需要部署两套环境, 一套是在本地windows服务器,jenkins从svn下载代码完成打包并上传到li ...

  2. 配置jQuery环境

    获取最新版jQuery 一.jq库类型说明 jQuery.js(开发版):完整无压缩,主要用于学习.开发和测试 jQuery.min.js(生产版):主要用于产品开发和项目 二.在页面引入 <s ...

  3. 表单传值给@Controller

    <form action="springmvc/testModelAttributes" method="post"> <input type ...

  4. Java容器解析系列(8) Comparable Comparator

    Comparable和Comparator接口是两个用于对对象进行大小比较的接口,在java集合相关类中,也被经常地使用到. 关于其使用,可以参考网络上的其他博客(没什么好说的);这里阐述关于这两个接 ...

  5. 分布式大数据系统离线分析技术解决方案(spark2.x)

    一.sark2.x新型的架构系统

  6. web前端之Javascript---function函数

    ---恢复内容开始--- js 支持两种函数:一类是语言内部的函数(如eval() ),另一类是自己创建的. 在 JavaScript 函数内部声明的变量(使用 var)是局部变量,所以只能在函数内部 ...

  7. 使用iframe框架后的页面跳转时目标页面变为iframe的子页面的问题

    <frameset rows="4,200,10,*,120" cols="*" framespacing="0" framebord ...

  8. js date setInterval 时间 时钟 getFullYear ,JavaScript

    js 创建时钟: 1.参考链接:  注意 getYear  (两位 或者 四位) 改成 getFullYear js操作时间 2.实例: html: <span class="glyp ...

  9. python 语法的一些特性记录

    装饰器@符号 装饰器本质上是一个 Python 函数或类,它可以让其他函数或类在不需要做任何代码修改的前提下增加额外功能,装饰器的返回值也是一个函数/类对象.它经常用于有切面需求的场景,比如:插入日志 ...

  10. centos下搭建openstack的环境

    一.准备环境 linux (centos 7.2(C300的虚机) ) java1.8 官网下载tar包 安装前设置环境变量 JAVA_HOME=/usr/lib/jvm/java-1.8.0-ope ...