Django接口文档的生成

Django接口文档两种生成方法

一.django-rest_framework风格接口文档：

1.安装依赖
pip install rest_framework #如果之前有了就跳过这步
pip install coreapi

2.setting.py设置

INSTALLED_APPS = [
	.....
    'rest_framework',
]
.....
REST_FRAMEWORK = {
	'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema',
}

3.项目整体 url.py 文件设置

from django.conf.urls import url
from rest_framework.documentation import include_docs_urls
urlpatterns = [
	.....
    url(r'docs/', include_docs_urls(title='接口文档'))
]

这里稍微提及一下接口文档中参数的解释主要取决于 filter.py或serializer.py 文件中 class Meta 中的字段，可以设置字段的 help_text 来为参数添加中文注释。我这里没深究，仅仅作为一个总结，filter.py中 fields中的字段能够起作用，而类中定义的 goods_id2 也能显示，但请求无效，所以尽量二者同名，便面接口生成多余参数。

class GoodsDetailFilter(filters.FilterSet):
    """
    商品的过滤类
    """
    goods_id2 = filters.NumberFilter(field_name="goods_id", lookup_expr='contains', help_text='商品id')  # 自定义字段

    class Meta:
        model = Goods
        fields = ['name','goods_id']

二.swagger接口文档生成

1.安装swagger
pip install django-rest-swagger

2.配置项目的settings文件

INSTALLED_APPS = [
	.....
    'rest_framework_swagger',
]

3.在views中添加注释内容,用于描述接口的功能等
例如：

class GoodsListSearch(CacheResponseMixin, mixins.ListModelMixin, mixins.RetrieveModelMixin, viewsets.GenericViewSet):
    """
    list:
        显示商品列表，分页、过滤、搜索、排序
    retrieve:
        显示商品详情
    """
    queryset = GoodsCategory.objects.all() 
 	.........

4.项目整体 url.py 文件设置

from rest_framework.schemas import get_schema_view
from rest_framework_swagger.renderers import SwaggerUIRenderer, OpenAPIRenderer
schema_view = get_schema_view(title='Users API', renderer_classes=[OpenAPIRenderer, SwaggerUIRenderer])

urlpatterns = [
    # swagger接口文档路由
    url(r'^docs/', schema_view, name="docs"),
]

两种方法访问接口文档路径：
http://127.0.0.1:8000/docs/