标签：title rest 文档 接口 swagger 图书 drf

drf自动生成接口文档

现在越来越流行前后端分离开发，使用ajax交互。所以api接口文档就变的十分有意义了。

文章目录

• drf自动生成接口文档
• • 一、介绍
  • 二、coreapi
  • • 1.自动生成接口文档配置
    • • 安装：
      • 配置
    • 2.文档描述说明的定义位置
    • 3.访问接口文档网页
    • 4.Description 描述信息的添加
  • 三、swagger
  • • 安装与配置
    • 1.安装
    • 2.配置
    • 文档描述说明的定义位置
    • 展示
    • 接口展示描述可以使用Markdown

一、介绍

• REST framework可以自动帮助我们生成接口文档
• 接口文档以网页的方式呈现
• 自动接口文档能生成的是继承APIView及其子类的视图

自动生成接口文档有很多种工具，这里我们主要以coreapi、swagger工具为例。

更多编写接口文档工具参考：https://blog.csdn.net/weixin_44185837/article/details/105933792

二、coreapi

官网链接：https://github.com/core-api/python-client

1.自动生成接口文档配置

安装：

pip3 install coreapi

配置

• settings.py 配置

# 因为新版的restframework需要指定默认schema
    REST_FRAMEWORK = {
            "DEFAULT_SCHEMA_CLASS": "rest_framework.schemas.AutoSchema",
            # 下面的这个默认的配置但是使用可能会报错，目前无法解释
            # 'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.openapi.AutoSchema',
        }

• urls.py路由配置，一般配置在总路由里面

# 导入文档路由哦配置
from rest_framework.documentation import include_docs_urls
# 添加访问路由，参数title为网站标题
urlpatterns = [
        path('docs/', include_docs_urls(title='测试接口'))
	]

2.文档描述说明的定义位置

1. 单一方法的视图，可以直接使用字符串描述该视图类的功能

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

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

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

    post:
    新建图书.
    """

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

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

    retrieve:
    返回图书详情数据

    latest:
    返回最新的图书数据

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

3.访问接口文档网页

浏览器访问 127.0.0.1:8000/docs/，即可看到自动生成的接口文档。

• 测试交互（新增测试）

• 查询所有

4.Description 描述信息的添加

• 在models.py的类字段参数 help_text

class Book(models.Model):
    title = models.Charfield(max_length=32)
    price = models.IntegerField(help_text='这是书籍的价格')

• 或者在序列化类中通过使用extra_kwargs为某字段添加额外的参数

class BookSerializers(ModelSerializer):
    class Meta:
        model = models.Book  # 指明该序列化器处理的数据字段从模型类Book参考生成
        fields = "__all__"  # 指明该序列化器包含模型类中的哪些字段，’all‘指明包含所有字段
        extra_kwargs = {
            'title': {
                'help_text': '这是书籍的名字'
            }
        }

注意：

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

三、swagger

官网：https://github.com/marcgibbons/django-rest-swagger

安装与配置

1.安装

pip install django-rest-swagger

2.配置

1. 在settings中注册app

INSTALLED_APPS = [
    'rest_framework_swagger',
]

2. 在urls.py中添加配置

# 添加 get_schema_view 辅助函数
from rest_framework.schemas import get_schema_view
from rest_framework_swagger.renderers import SwaggerUIRenderer,OpenAPIRenderer

# 参数 title 为接口网站标题
schema_view=get_schema_view(title='测试接口',renderer_classes=[OpenAPIRenderer,SwaggerUIRenderer])

# 添加路由
urlpatterns = [
    # coreapi
    path('docs/', include_docs_urls(title='接口测试')),
    # swagger
    path('docs2/', schema_view, name='docs2'),
]

文档描述说明的定义位置

• 与 上面的coreapi 工具中的使用相同

展示

• 页面展示

• 功能介绍

• GET获取所有接口测试

• POST新增图书测试

接口展示描述可以使用Markdown

• 描述书写示例

class BookView2(ModelViewSet):
    """
       ## list:
       - 返回图书列表数据，通过Ordering字段排序

       ## retrieve:
       - 返回图书详情数据

       ## latest:
       - 返回最新的图书数据

       ## read:
       - 查询单个图书接口

       #### 请求参数
        | 字段名| 含义  | 类型   |
        |:------:|:------:|:------:|
        | title | 书籍名称    |  string |
        | price | 价格    |  int |
       """
    ...

• 效果展示

标签：title,rest,文档,接口,swagger,图书,drf
来源： https://blog.csdn.net/weixin_44621343/article/details/116033596

本站声明： 1. iCode9 技术分享网（下文简称本站）提供的所有内容，仅供技术学习、探讨和分享；
2. 关于本站的所有留言、评论、转载及引用，纯属内容发起人的个人观点，与本站观点和立场无关；
3. 关于本站的所有言论和文字，纯属内容发起人的个人观点，与本站观点和立场无关；
4. 本站文章均是网友提供，不完全保证技术分享内容的完整性、准确性、时效性、风险性和版权归属；如您发现该文章侵犯了您的权益，可联系我们第一时间进行删除；
5. 本站为非盈利性的个人网站，所有内容不会用来进行牟利，也不会利用任何形式的广告来间接获益，纯粹是为了广大技术爱好者提供技术内容和技术思想的分享性交流网站。