drf09 自动化接口文档-coreapi

目录

• 一、 自动生成接口文档
  • 1. 安装依赖
  • 2. 设置接口文档访问路径
  • 3. 文档描述说明的定义位置
    • 3.1 单一方法的视图
    • 3.2 包含多个方法的视图
    • 3.3 对于视图集ViewSet
  • 4. 访问接口文档网页
    • • 两点说明：
  • 5.补充 - swagger使用 - 有坑未解决
    • 5.1 安装
    • 5.2 配置
      • settings.py
      • urls.py

一、 自动生成接口文档

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

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

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

https://www.kernel.org/doc/html/v4.12/core-api/index.html

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='drf接口文档'))
]

如果报错了下面的错误，说明我们缺少一个依赖，配置一下就行了

'AutoSchema' object has no attribute 'get_link'

配置：

REST_FRAMEWORK = {
    ...
    'DEFAULT_SCHEMA_CLASS': "rest_framework.schemas.AutoSchema",

}

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

3.1 单一方法的视图

可直接使用类视图的文档字符串，如

class BookListView(generics.ListAPIView):
    """
    get: 返回所有图书信息.
    post: 添加记录
    """
    #注意，这是在类中声明的注释，如果在方法中你声明了其他注释，会覆盖这个注释的

3.2 包含多个方法的视图

在类视图的文档字符串中，分开方法定义，如

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

    post:
    新建图书.
    """

3.3 对于视图集ViewSet

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

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

    retrieve:
    返回图书详情数据

    latest:
    返回最新的图书数据

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

4. 访问接口文档网页

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

两点说明：

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

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

class Book(models.Model):
    ...
    title = models.IntegerField(default=0, verbose_name='书名', help_text='需要输入书名')
    ...

或 注意，如果你多个应用使用同一个序列化器，可能会导致help_text的内容显示有些问题，小事情

class StudentSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = "__all__"
        extra_kwargs = {
            'title': {
                'required': True,
                'help_text': '需要输入书名'
            }
        }

5.补充 - swagger使用 - 有坑未解决

5.1 安装

# 1.安装
pip install django-rest-swagger - 已弃用
# 推荐安装
pip install drf-yasg2

5.2 配置

settings.py

INSTALLED_APPS = [
    'app07_doc',
    'drf_yasg2' # 注册这个
]

urls.py

from rest_framework import permissions
from drf_yasg2.views import get_schema_view
from drf_yasg2 import openapi
schema_view = get_schema_view(
    openapi.Info(
        title="Tweet API",
        default_version='v1',
        description="Welcome to the world of Tweet",
        terms_of_service="https://www.tweet.org",
        contact=openapi.Contact(email="demo@tweet.org"),
        license=openapi.License(name="Awesome IP"),
    ),
    public=True,
    permission_classes=(permissions.AllowAny,),
)



 re_path(r'^doc(?P<format>\.json|\.yaml)$',schema_view.without_ui(cache_timeout=0), name='schema-json'),  
    path('doc/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),  
    path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),