写文档是一个程序开发者的基本素养之一, 虽然我可能并没有做到T.T
前言
这首先取决于公司的体量吧, 如果是大公司, 前后端之间的沟通也往往比较正规, 这时文档由不得你不写.
不过如果是小公司, 大家沟通基本靠吼, 再加上初期业务繁忙, 可能很多人都会懒得写文档. 不过随着项目越做越大, 代码越来越多, api文档最好还是补上, 不然某一天产品找出一个一年前的api问你, 可能一时半会儿还真回答不上
选型
这其实是个很开放的问题. 你可以用swagger, 也可以用浓浓的官方风格的readthedocs, 哪怕偷个懒用wiki, 甚至写个word...
在这里我们不管那么多, 选个最顺眼的, 毕竟少说也要面对它面对个一年, 就用swagger了
django对swagger也有特殊的库支持, 接下来简单说两个
1. django-rest-swagger
这个看名字就有点官方气息. 事实上你去搜django swagger其实大多数搜出来的也是这个. 不过有点让人失望的是这个其实还真不太好用, 尤其是对json, array字段的支持很不足.
简单说下, 首先安装上述库pip install
然后settings.py中添加
INSTALLED_APPS = [
...
'rest_framework_swagger',
...
]
如果你是https:
SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')
基础配置
SWAGGER_SETTINGS = {
# 基础样式
# 'SECURITY_DEFINITIONS': {
# "basic": {
# 'type': 'basic'
# }
# },
'USE_SESSION_AUTH': True,
'SECURITY_DEFINITIONS': {
'api_key': {
'type': 'apiKey',
'in': 'header',
'name': 'authorization'
}
},
# 如果需要登录才能够查看接口文档, 登录的链接使用restframework自带的.
# 'LOGIN_URL': '/api/v1/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,
}
如果你重写了login的api, 上述LOGIN_URL记得指向你的新url.
以及如果你用了jwt, 某些api可能会无法请求, 记得配置SECURITY_DEFINITIONS, 里面的name: authorization 是你消息头里的验证信息.
然后写个view
from rest_framework_swagger.views import get_swagger_view
schema_view = get_swagger_view(title='MS.HAN API')
指向url
urlpatterns += [
url(r'v1/docs/', schema_view, name="docs")
]
2. drf-yasg
yasg - Yet another Swagger generator
情不自禁的想起这张图
但是跟上述比起来挺好用的, 而且项目好像还在持续更新.
而且这个还有不同风格的页面可以选择, 对json格式也有额外的支持.
首先依然pip install drf-yasg
settings.py中添加
INSTALLED_APPS = [
...
'drf_yasg',
]
urls.py中添加
# swagger
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi
schema_view_2 = get_schema_view(
openapi.Info(
title="Snippets API",
default_version='v1',
description="Test description",
terms_of_service="https://www.google.com/policies/terms/",
contact=openapi.Contact(email="contact@snippets.local"),
license=openapi.License(name="BSD License"),
),
public=True,
permission_classes=(permissions.AllowAny,),
)
urlpatterns += [
url(r'^v1/swagger(?P<format>\.json|\.yaml)$', schema_view_2.without_ui(cache_timeout=0), name='schema-json'),
url(r'^v1/swagger/$', schema_view_2.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
url(r'^v1/redoc/$', schema_view_2.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
]
注意
如果你部署在非debug环境上可能会发生无法读取静态资源的情况, 见 django static
