写文档是一个程序开发者的基本素养之一, 虽然我可能并没有做到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
情不自禁的想起这张图

319722082.jpg

505088971.jpg

但是跟上述比起来挺好用的, 而且项目好像还在持续更新.
而且这个还有不同风格的页面可以选择, 对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