DRF__自动生成接口文档

drf生成接口文档

方式1：coreapi

安装依赖：

1. coreapi
2. Pygments （可选）
3. Markdown （可选）

配置

settings的相关配置

如果drf的版本在3.10以上，需要在settings中的REST_FRAMEWORK中配置如下：

REST_FRAMEWORK = {
    "DEFAULT_SCHEMA_CLASS": "rest_framework.schemas.coreapi.AutoSchema",
}

根路由的配置

在根路由中添加如下代码：

from rest_framework.documentation import include_docs_urls

urlpatterns=[
    # api-docs url
    path('api-docs/', include_docs_url(title='接口文档',description='这是一个接口文档的demo'))
]

这里的include_docs_url参数还可以配置 认证、授权等等

添加注解内容

一个好的接口文档需要对接口的各个字段进行解释，并且对每个接口是干嘛的进行相关解释

访问上述配置好的链接：127.0.0.1:8000/api-docs/ 看到接口文档页面如下：

第一个接口有接口的描述内容，但是有的字段有字段的描述内容，有的没有， 第二个接口没有接口描述内容，但是主键id的描述给了一个默认的

添加接口描述

通用视图类中

class DemoView(generics.APIView):
    """
    get:
    这里填写get请求的描述内容
    
    post:
    这里填写post请求的内容
    """
    def get():
        ...
    def post():
        ...

视图集中

class DemoViewSet(ModelViewSet):
    """
    create:
    这里添加action为 create的描述内容
    
    list:
    这里添加action为 list的描述内容
    """

综上，在添加接口的描述内容时，视图类是对应不同的请求get post put patch等等，视图集中是对应不同的action，注意两者的声明方式的区别

添加接口字段描述

接口字段的描述相当重要，这里是从对应模型类的help_text属性中带出来的，比如：

class Article(models.Model):
    title = models.CharField(max_length=50, help_text="标题")
    body = models.TextField(help_text="文章的内容")
    created = models.DateField(default=timezone.now)
    updated = models.DateField(auto_now=True)
    author = models.ForeignKey(User, on_delete=models.CASCADE, related_name="xxx", help_text="外键关联django自带的User表")
    category = models.ForeignKey(to='Category', on_delete=models.SET_NULL, null=True, blank=True,
                                 related_name='articles')
    tags = models.ManyToManyField(to='Tag', through='Artile_Tag', through_fields=('article', 'tag'),
                                  related_name='articles')

    def __str__(self):
        return self.title

    class Meta:
        ordering = ['-updated']

如上这么多字段，在接口文档中会发现，其中有些字段并没有展示出来，因为在序列化类中，我们定义了一些字段为read_only，这里的接口文档只会带出序列化时 定义的可以传递的参数，并且注明 是不是必填字段

---

方式2：swagger

安装依赖：

1. drf-yasg

配置

在根路由中添加配置如下：

from drf_yasg.views import get_schema_view
from drf_yasg import openapi

# swagger配置
schema_view = get_schema_view(
    openapi.Info(
        title="swagger接口文档",  # required
        default_version="v1",  # required
        description="title下面的描述",
        # terms_of_service="",
        contact=openapi.Contact(email="alan.qin@lixinchuxing.com"),
        license=openapi.License(name="test str"),
    ),
    public=True,
    # permission_classes=(),  # 权限类
)

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

urlpatterns += swagger_url_patterns

接口和字段描述

接口的描述

在对应的视图类中添加注释如下：

class ArticleViewSet(viewsets.ModelViewSet):
    '''
    create:
    创建一个新的数据

    list:
    展示所有的article列表
    '''

在swagger中可以看到描述内容：

字段的描述