【python之DRF学习】 drf之接口文档介绍及使用

49.【python之DRF学习】 drf之接口文档介绍及使用2024-04-21

50.【python之DRF学习】drf之jwt使用2024-04-21

title:  【python之DRF学习】 drf之接口文档介绍及使用
date:  2024-04-21 14:02:12 星期日
updated: 2024-04-21 14:02:16 星期日
description: 
cover:  http://blog.shabbywu.cn/posts/2020/04/15/python-auto-doc-for-drf.html

一、简述

在项目开发中，例如web项目的前后端分离开发，需要由前后端相关人员共同定义接口，编写接口文档。之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护。一个好的接口文档能够帮助我们快速上手这类项目、便于阅读已有代码、对接接口自动化测试等等

往往一个清晰的API接口文档编写起来比较费时费力，于是有很多接口文档管理工具供我们使用：YApi、ShowDoc、DocWay，以及可直接利用接口测试生成接口文档的工具Postman、Apipost、postwoman等

上面列出的工具或多或少都需要花费一定时间去手动维护，在drf后端项目中可以利用其自带的Core API、第三方库Swagger以及更好的drf-yasg自动生成接口文档


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

二、接口文档的展现形式

-1 world、md，编写,大家都可以操作，写完放在git;公司的文档管理平台上
-2 第三方的接口文档平台(收费)
https://www.showdoc.com.cn/
-3 公司自己开发接口文档平台
-4 公司使用开源的接口文档平台，搭建
-YAPI：百度开源的
搭建yapi文档详见【python之接口工具】利用docker-compose搭建Yapi
-5 项目自动生成接口文档
-coreapi
-swagger

三、接口文档编写规范

以用户注册接口为例：
　　1. 接口描述
　　2. 请求地址
　　3. 请求方式
　　4. 编码格式：json，urlencoded，form-data
　　5. 请求参数：写参数的详解
　　　　- 请求地址参数
　　　　- 请求体参数
　　6. 返回格式示例：要有返回参数说明
　　7. 备注（可有可无）：写错误码的

有具体参照接口文档模板：各个大网站的开放平台都有相关的文档

四、CoreApi接口文档

参考Core API官网以及drf官网，最终生成的接口文档是以网页的方式呈现的，自动接口文档能生成的是继承自APIView及其子类的视图，具体实现流程如下

1、coreapi安装

pip3 install coreapi

2、添加路由接口文档访问路径

在总路由中添加接口文档路径。  
-- 在项目路由中配置(比如当前项目创建为drf_user_test_1，应用路由为app01，此时的路由应该在drf_user_test_1下的urls中进行配置)
文档路由对应的视图配置为rest_framework.documentation.include_docs_urls，
参数title为接口文档网站的标题。

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

在配置文件中配置接口文档配置(settings.py)

REST_FRAMEWORK = {
    # core api接口文档
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
}

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

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:
    修改图书的阅读量
    """
    # 如
    @action(detail=False,methods=['POST'])
    def list(self,request,*args,**kwargs):
      ...

4、访问接口文档网页

两点要说明
1） 视图集ViewSet中的retrieve名称，在接口文档网站中叫做read
2）参数的Description需要在模型类或序列化器类的字段中以help_text选项定义，如：

class BookInfo(models.Model):
    ...
    bread = models.IntegerField(default=0, verbose_name='阅读量', help_text='阅读量')
    ...
    
或者：

# 这里是在序列化器类中进行修改
class BookReadSerializer(serializers.ModelSerializer):
    class Meta:
        model = BookInfo
        fields = ('bread', )
        extra_kwargs = {
            'bread': {
                'required': True,
                'help_text': '阅读量'
            }
        }

五、drf-yasg生成接口文档

1、Swagger介绍

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。总体目标是使客户端和文件系统源代码作为服务器以同样的速度来更新。

当接口有变动时，对应的接口文档也会自动更新

2、drf-yasg介绍

drf-yasg是基于Swagger和OpenAPI 2.0规范的API文档自动化生成工具，能够生成比原生swagger更为友好的API文档界面
drf-yasg是swagger的升级版

目前使用的版本：
python： 3.10
drf（django rest framework）
django： 4.2.11

3、drf安装使用

pip3 install drf-yasg
pip3 freeze > requirements.txt

4、配置settings.py

INSTALLED_APPS = [
    ...
    'rest_framework',
    'drf_yasg'
]

5、配置路由

from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi
...

schema_view = get_schema_view(
    # 具体定义详见 [Swagger/OpenAPI 规范](https://swagger.io/specification/#infoObject)
    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 表示文档完全公开, 无需针对用户鉴权
    public=True,
    # 可以传递 drf 的 BasePermission
    permission_classes=(permissions.AllowAny,),
)

urlpatterns = [
    # drf_yasg
    re_path(r'^swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-spec'),
    re_path(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
    re_path(r'^redoc/$', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
    ...
]

drf-yasg会暴露4种默认路径endpoint, 分别为:

/swagger.json, JSON 格式的 API 定义
/swagger.yaml, YAML 格式的 API 定义
/swagger/, 基于原生 swagger-ui 样式的前端页面
/redoc/, 基于 ReDoc 样式的前端页面

6、访问验证

配置完成后重启项目进行访问

swagger：

redoc：

7、配置及说明

1、get_schema_view配置说明

函数 get_schema_view 的作用是返回自动生成 API 文档的视图类, 该函数接受以下参数:

info: Swagger API Info对象, 具体定义详见 Swagger/OpenAPI 规范, 如果缺省, drf-yasg默认会用 DEFAULT_INFO 进行填充
url: 项目API的基础地址, 如果缺省, 则根据视图所在的位置进行推导
patterns: 自定义的urlpatterns, 该参数直接透传至SchemaGenerator
urlconf: 描述从哪个文件获取路由配置, 缺省值是urls, 该参数直接透传至SchemaGenerator
public: 描述API文档是否公开, 如果未 False, 则仅返回当前用户具有权限的接口endpoints的API文档
validators: 用于校验自动生成的Schema的校验器, 目前仅支持 ssv 和 flex
generator_class: 自定义OpenAPI schema生成器类, 该类应该继承自 OpenAPISchemaGenerator
authentication_classes: 用于schema view进行登录认证的类
permission_classes: 用于schema view进行权限校验的类

2、SchemaView 的配置

通过函数get_schema_view可以获取对应的SchemaView, 调用该类的with_ui或 without_ui方法可生成对应的视图函数, 将其添加进urlpatterns即可访问到自动生成的 API 文档

SchemaView.with_ui(renderer, cache_timeout, cache_kwargs): 返回使用指定UI渲染器的视图函数, 可选的UI渲染器有: swagger, redoc。
SchemaView.without_ui(cache_timeout, cache_kwargs): 返回无UI的视图函数, 该函数可以返回json/yaml格式的swagger文档
以上两个函数均支持通过 cache_timeout 或 cache_kwargs 配置缓存参数

3、缓存配置

由于schema通常在服务运行期间不会发生改变, 因此 drf-yasg使用django内置的 cache_page 实现开箱即用的缓存功能, 只需要配置对应的参数即可启用, 对应参数解释如下:

cache_timeout: 用于指定缓存的生存时间
cache_kwargs: 用于传递 cache_page 允许接受的非位置参数, 如 cache(指定 cache backend), key_prefix(缓存key的前缀) 等等, 详见django官方文档
 需要注意的是, 由于 drf-yasg 支持针对不同用户返回不一样的 API 文档(通过public、authentication_classes、permission_classes等参数配置), 因此对于不同用户(通过HTTP 请求头中的 Cookie 和 Authorization 进行区分), 会在内存中分别进行缓存。

4、校验文档有效性

为保证自动生成文档的有效性, 可以通过在get_schema_view中设置 validators 参数开启校验自动化生成文档是否符合OpenAPI2.0规范的功能

5、代码自动生成

使用Swagger/OpenAPI规范生成文档的好处之一, 就是能通过API文档自动生成不同语言的 SDK，该功能由swagger-codegen提供

posted @ 2024-04-21 14:06 Unfool 阅读(13) 评论(0) 编辑收藏举报

刷新页面返回顶部

（评论功能已被禁用）

相关博文：

· 【python之DRF学习】DRF入门了解

· 【python之DRF学习】drf之jwt使用

· drf自动生成接口文档

· django项目中使用swagger来实现接口文档自动生成

· drf09 自动化接口文档-coreapi

阅读排行：
· 阿里最新开源QwQ-32B，效果媲美deepseek-r1满血版，部署成本又又又降低了！
· 单线程的Redis速度为什么快？
· SQL Server 2025 AI相关能力初探
· AI编程工具终极对决：字节Trae VS Cursor，谁才是开发者新宠？
· 展开说说关于C#中ORM框架的用法！

公告

昵称： Unfool
园龄： 1年3个月
粉丝： 4
关注： 2

+加关注

2025年3月

日

一

二

三

四

五

六

queryH