手把手程式實作分享系列: Swagger and Django 自定義文檔 drf-yasg

還沒看過基本教學的朋友，如果想先了解基本Swagger設定的，先往上一篇走。 傳送門提供在下方

手把手程式實作分享系列: Swagger and Django基本入門教學

這篇是為了客製化定義API的說明而生的分享章節。GOGOGO

0. 安裝

pip install -U drf-yasg

沒什麼好解釋的。

1. Setting.py 設定

上次加入的是rest_framework_swagger，自定義的部分記得加入drf_yasg。

INSTALLED_APPS = [
…
‘drf_yasg’,
…
]

2. url.py的設定

修改 Django REST framework project 的 urls.py 新增 drf_yasg 的 URL（建議修改 openapi.Info 的 title、contact 等資訊）：

...
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi...schema_view = get_schema_view(
   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=True,
   permission_classes=(permissions.AllowAny,),
)urlpatterns += [
   url(r'^swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'),
   url(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
   url(r'^redoc/$', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
   ...
]

schema_view = get_schema_view 那一段在定義的是swagger首頁ux的一些參數，應該都看得懂，就稍微紀錄一下團隊的資訊。

下面link的部分

#這一段是在和django 連接 swagger的介面

path(‘’, schema_view.with_ui(‘swagger’,cache_timeout=0), name=’schema-swagger-ui’),

#然後用串接的方式 從最外層的url 連接到 到下層的app url.py

path('swagger_server/', include(('swagger_server.urls', 'swagger_server'),namespace="swagger_server")),

3. 定義下層的app url.py

這邊重點是連接自身的view.py ˊ
一定要跟下一層的view.py 串好才會顯示出來喔

from django.urls import path
from .views import MusicViewSet,doct_list 
urlpatterns = [
 path(‘MusicViewSet/’, MusicViewSet.as_view()),
 path(‘doct_list/’, doct_list.as_view()),
]

4. view.py 的設定

Django 透過 view.py 設定 RESTful api

我們swagger 是來管理這些東西的，那客製化寫一些README是理所當然的。

我們來看看範例:

這樣就完成一個簡單而且有註解的api了!

是不是很簡單呢!

from drf_yasg.utils import swagger_auto_schema
from rest_framework.generics import GenericAPIVie
class doct_list(GenericAPIView):
 serializer_class = MusicSerializer
 @swagger_auto_schema( 
 operation_summary=’簡單API’,
 operation_description=’這是註解',)
 
 def post(self, request):
 pass
 return Response(data, status=status.HTTP_200_OK)
 def get(self, request):
 pass
 return Response(data, status=status.HTTP_200_OK)

*** model.py 跟serializers.py不解釋 就是造原來的設定即可

關於參數客製化的文章也可以參考這一篇

自定義 drf-yasg 的 Swagger 文檔— 以 GET、POST、檔案上傳為例

然後這邊有一個人家的github也附上給大家參考

CryceTruly/incomeexpensesapi

reference:

用 Django REST Framework 撰寫 RESTful API 並生成 Swagger 文檔（下） — 生成 Swagger 文檔