django-rest-framework-swagger-tutorial

Django-REST-Swagger 基本教學

Youtube Tutorial

相信大家在網路上一定都看過 API 文件，

那我們該如何撰寫 API 文件 給別人看呢？

今天我要教大家使用 drf-yasg 來完成他！！

溫馨小提醒

建議大家先對 Django 以及 Django REST framework ( DRF ) 有基礎的知識。

如果還不熟的人，可以先閱讀我之前寫的

Django 基本教學 - 從無到有 Django-Beginners-Guide

以及

Django-REST-framework 基本教學 - 從無到有 DRF-Beginners-Guide

先建立一些基本觀念，再來看這篇比較清楚。

教學

我們依照 Django-REST-framework 基本教學 - 從無到有 DRF-Beginners-Guide 這篇繼續延伸下去。

請在你的命令提示字元 (cmd ) 底下輸入

安裝 drf-yasg

pip install drf-yasg

drf-yasg 設定

請記得要將 drf-yasg 加入設定檔

請在 settings.py 裡面的 INSTALLED_APPS 加入下方程式碼

INSTALLED_APPS = (
    ...
    'django.contrib.staticfiles',
    'drf_yasg',
    'rest_framework',
)

接著我們設定 Routers 路由，請將 urls.py 增加一些程式碼

......

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,
   public=False, # need login
   permission_classes=[permissions.AllowAny],
)

urlpatterns = [
    path('admin/', admin.site.urls),

    # for rest_framework
    path('api/', include(router.urls)),
    # for rest_framework auth
    path('api-auth/', include('rest_framework.urls', namespace='rest_framework')),

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

最後執行 Django ，然後瀏覽 http://127.0.0.1:8000/swagger/

你應該會看到如下圖 (如果你沒看到任何東西，可以點一下 Show/Hide )

也可以瀏覽 http://127.0.0.1:8000/redoc/

執行畫面

畫面非常漂亮，功能也非常完善，

我們可以在上面執行 GET , POST , PUT , PATCH , DELETE , 甚至可以直接看到執行結果，

我介紹幾個給大家當範例，看完大家就會比較了解

POST

點選編號 1 的地方，他會幫你把範例貼到左手邊，修改完值之後，直接按 Try it out!

接著你會發現下面有 Response ，以這個範例來講，201 就是新增成功

GET

接著我們再去 GET ，我們剛剛新增的那筆的確有在裡面

有沒有發現非常強大 😮

接下來你可能會擔心，這樣我的資料不就會被任何人任意操作?

不用擔心，和之前介紹的授權 (Authentication) 是一樣的。

授權（ Authentication ）

在 urls.py 底下程式碼,

urlpatterns = [
    ......
    # for rest_framework auth
    path('api-auth/', include('rest_framework.urls', namespace='rest_framework')),
    ......
]

在 views.py 底下加入 permission

# Create your views here.
class MusicViewSet(viewsets.ModelViewSet):
    queryset = Music.objects.all()
    serializer_class = MusicSerializer
    permission_classes = (IsAuthenticated,)

在 settings.py 底下加入下方程式碼

設定 SWAGGER_SETTINGS 為使用 rest_framework login, logout

SWAGGER_SETTINGS = {
    'LOGIN_URL': 'rest_framework:login',
    'LOGOUT_URL': 'rest_framework:logout'
}

也要把 urls.py 中的 public 設為 False.

可參考 https://drf-yasg.readthedocs.io/en/stable/settings.html

執行 Django, 然後瀏覽 http://127.0.0.1:8000/swagger/

你會發現，當你沒有登入的時候，你是看不到這些 API 的內容,

登入之後你才有權限可以看到這些資料

我的帳號/密碼設定為 twtrubiks/password123 ，

Swagger 的基本介紹我們就介紹到這邊，更多的說明可以參考 drf-yasg

twtrubiks/django_rest_framework_swagger_tutorial

django-rest-framework-swagger-tutorial

教學

drf-yasg 設定

執行畫面

授權（ Authentication ）

執行環境

Reference

License