django rest 接口 自动生成文档

尝试1 djangorestframwork自带的

(界面不友好,切有bug 字段描述出不来)
urls配置

from rest_framework.documentation import include_docs_urls
urlpatterns = [
    ...
    url(r'^docs/', include_docs_urls(title="myapp")),#这个自带的有bug
]

尝试2 rest_framework_swagger

(界面不友好)
pip install django_rest__swagger
setting配置

# swagger 配置项
SWAGGER_SETTINGS = {
    # 基础样式
    'SECURITY_DEFINITIONS': {
        "basic":{
            'type': 'basic'
        }
    },
    # 如果需要登录才能够查看接口文档, 登录的链接使用restframework自带的.
    'LOGIN_URL': 'rest_framework:login',
    'LOGOUT_URL': 'rest_framework:logout',
    # 'DOC_EXPANSION': None,
    # 'SHOW_REQUEST_HEADERS':True,
    # 'USE_SESSION_AUTH': True,
    # 'DOC_EXPANSION': 'list',
    # 接口文档中方法列表以首字母升序排列
    'APIS_SORTER': 'alpha',
    # 如果支持json提交, 则接口文档中包含json输入框
    'JSON_EDITOR': True,
    # 方法列表字母排序
    'OPERATIONS_SORTER': 'alpha',
    'VALIDATOR_URL': None,
}

urls配置

from rest_framework.schemas import get_schema_view
urlpatterns = [
    ...
    url(r'^docs', get_schema_view(title='Users API', renderer_classes=[OpenAPIRenderer, SwaggerUIRenderer]), name="docs"),
]

尝试3 apidoc (非常棒)(零学习成本)(适用任何情景)(强烈推荐)

01.安装

npm install apidoc   
#(注意与"pip install apidoc"安装的不是同一个,一定要用npm安装)

02.配置

项目根目录(或者运行终端命令的当前目录),添加apidoc.json

{
  "name": "老邢接口",
  "version": "1.0.0",
  "description": "老邢接口-description",
  "title": "老邢接口-title",
  "url" : "http://xx.xx.xx.xx:8000"
}

03.代码注释

例如:(下面是python, 其他语法请参考文章结尾的官方文档)

def login():
 """
 @api {POST} /login/ 登录操作
 @apiVersion 0.0.1
 @apiName login
 @apiGroup User
 @apiDescription 这里可以描述一下这个函数的具体操作
 这一行也是可以描述的

 @apiParam {String} name 姓名
 @apiParam {String} password 密码

 @apiSuccess {Object} status 状态码
 @apiSuccess {Object} msg 简略描述

 @apiSuccessExample Response-Success:
     HTTP 1.1/ 200K
     {
         'status': 0,
         'msg': 'success'
     }
 @apiErrorExample Response-Fail:
     HTTP 1.1/ 404K
     {
         'status': 1,
         'msg': 'Fail'
     }
 """
 pass

04.运行命令

apidoc -i myapp/ -o  docs/
#-i 源码目录 
#-o 输出目录

05.ok可以查看结果啦

image.png

apidoc 支持挺多语言的, 而且用法也很简单
官方文档 详情 http://apidocjs.com