DRF__自動生成介面文件
阿新 • • 發佈：2021-09-01
drf生成介面文件
方式1：coreapi
安裝依賴：
- coreapi
- Pygments （可選）
- 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
安裝依賴：
- 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="[email protected]"),
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中可以看到描述內容：