33 drf 自动生成接口文档

201次阅读
没有评论

共计 2239 个字符,预计需要花费 6 分钟才能阅读完成。

一. 自动生成接口文档

1. 介绍

  • REST framework 可以自动帮助我们生成接口文档, 并且接口文档以网页的方式呈现
  • 自动接口文档能生成的是继承自 APIView 及其子类的视图
  • 下面介绍两种自动生成接口文档工具 : coreapiswagger

二.coreapi

1. 使用步骤

  • 安装 coreapi 依赖库
pip3 install coreapi
  • settings.py 配置
REST_FRAMEWORK = {
    # 自动生成接口文档
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
}
  • urls.py 路由配置
# 导入文档路由配置
from rest_framework.documentation import include_docs_urls

# 添加访问路由, 参数 title 为接口网站标题
path('docs/', include_docs_urls(title='接口测试')),

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

  • 单一方法的视图, 可以直接使用字符串描述该视图类的功能
class BookListView(generics.ListAPIView):
    """
    返回所有图书信息
    """
  • 多个方法的视图, 可以分别对方法进行描述
class BookListCreateView(generics.ListCreateAPIView):
    """
    get:
    返回所有图书信息

    post:
    新建图书
    """
  • 对于视图集 ViewSet, 你继承了多少个视图类就书写多少个 action 名称及介绍
class BookView2(ModelViewSet):
    """
       list:
       返回图书列表数据,通过 Ordering 字段排序

       retrieve:
       返回图书详情数据

       latest:
       返回最新的图书数据

       read:
       查询单个图书接口
       """

3. 在网页上进行访问文档

  • 通过访问接口文档的路由可以看到结果

33 drf 自动生成接口文档

  • 测试交互 (新增测试)

33 drf 自动生成接口文档

  • 查询所有

33 drf 自动生成接口文档

4.Description 描述信息的添加

33 drf 自动生成接口文档

  • models.py 的类字段参数 help_text
class Book(models.Model):
    title = models.CharField(max_length=32)
    price = models.IntegerField(help_text='这个是书籍的价格!!')
  • 或者在序列化类中通过使用 extra_kwargs 为某字段添加额外的参数
class BookModelSerializer(serializers.ModelSerializer):
    class Meta:
        model = models.Book
        fields = "__all__"
        extra_kwargs = {
            'title': {'help_text': '这是书籍的名字!!'}
        }

33 drf 自动生成接口文档

5. 报错问题解决

  • 抛出 : AttributeError: 'AutoSchema' object has no attribute 'get_link' 错误

33 drf 自动生成接口文档

# 新版本 drf 默认使用的配置(没有配置就是使用这个)
REST_FRAMEWORK = {'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.openapi.AutoSchema',}

# 需要将其改为
REST_FRAMEWORK = {'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',}

6. 小变化

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

二.swagger

1. 使用步骤

  • 安装 Swagger 工具
pip install django-rest-swagger
  • 在 settings.py 中注册 app
INSTALLED_APPS = ['rest_framework_swagger',]
  • 在 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'),
]

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

  • coreapi 工具中的使用相同

3. 测试

  • 页面展示

33 drf 自动生成接口文档

  • 功能介绍

33 drf 自动生成接口文档

  • GET 获取所有接口测试

33 drf 自动生成接口文档

  • POST 新增图书测试

33 drf 自动生成接口文档

4. 接口功能描述可以使用 Markdow 语法

  • 描述书写示例
class BookView2(ModelViewSet):
    """
       ## list:
       - 返回图书列表数据,通过 Ordering 字段排序

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

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

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

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

33 drf 自动生成接口文档

正文完
 
shawn
版权声明:本站原创文章,由 shawn 2023-06-16发表,共计2239字。
转载说明:除特殊说明外本站文章皆由CC-4.0协议发布,转载请注明出处。
评论(没有评论)