一、自动生成接口文档

REST framework可以自动帮助我们生成接口文档。

接口文档以网页的方式呈现。

自动接口文档能生成的是继承自APIView及其子类的视图。

1、安装依赖

REST framewrok生成接口文档需要coreapi库的支持。

pip install coreapi

2、设置接口文档访问路径

在总路由中添加接口文档路径。

文档路由对应的视图配置为rest_framework.documentation.include_docs_urls，

参数title为接口文档网站的标题。

from rest_framework.documentation import include_docs_urls

urlpatterns = [
    ...
    path('docs/', include_docs_urls(title='站点页面标题'))
]

3、文档描述说明的定义位置

3.1、单一方法的视图，可直接使用类视图的文档字符串，如

class BookListView(generics.ListAPIView):
    """
    返回所有图书信息.
    """

3.2、包含多个方法的视图，在类视图的文档字符串中，分开方法定义，如

class BookListCreateView(generics.ListCreateAPIView):
    """
    get:
    返回所有图书信息.

    post:
    新建图书.
    """

3.3、对于视图集ViewSet，仍在类视图的文档字符串中封开定义，但是应使用action名称区分，如

class BookInfoViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin, GenericViewSet):
    """
    list:
    返回图书列表数据

    retrieve:
    返回图书详情数据

    latest:
    返回最新的图书数据

    read:
    修改图书的阅读量
    """

4、访问接口文档网页

如果遇见报错：

# AttributeError: 'AutoSchema' object has no attribute 'get_link'# 解决：配置文件添加配置 REST_FRAMEWORK = { 'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',    # 新版drf schema_class默认用的是rest_framework.schemas.openapi.AutoSchema}

5、两点说明

1） 视图集ViewSet中的retrieve名称，在接口文档网站中叫做read

2）参数的Description需要在模型类或序列化器类的字段中以help_text选项定义，如：

class Student(models.Model):
    ...
    age = models.IntegerField(default=0, verbose_name='年龄', help_text='年龄')
    ...

或

class StudentSerializer(serializers.ModelSerializer):
    class Meta:
        model = Student
        fields = "__all__"
        extra_kwargs = {            'age': {                'required': True,                'help_text': '年龄'
            }
        }

做开发经常会碰到这样的情况，前期写了接口文档，后端把需求改完没时间更新接口文档，想想就觉得崩溃了。那么有没有方法能自动生成接口文档来提高前后端的开发效率呢？

自定义动态生成接口文档，手动部署

在对外暴露的接口上添加一套自定义注解。注解可指定接口名称，请求 url，请求方式，请求参数，请求参数类型，返回参数，返回参数类型等信息。通过解析 controller 类上注解和方法上的注解，生成获取所有对外暴露方法的定义的接口，然后通过 web 页面呈现所有接口定义。

项目组所有人使用Swagger，统一标准

项目集成 Swagger 插件，添加Swagger依赖，前端人员访问 Swagger 生成的接口文档，查看和使用接口。

使用Eolinker，根据需求导出不同格式接口文档

后端开发直接将项目导入到Eolinker，完善需求时会自动生成接口代码，导入和导出均支持多种格式，通用性较高。
使用地址：www.eolinker.com

最后

本文的思考来源于工作。项目接口文档本应该就是根据代码同时发布的，在多加一步操作，将生成的接口文档自动部署到服务上，就实现接口文档的自动更新，一劳永逸！

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。