介紹

  • 由於目前在正在做一個專案，寫了一個Web API，需要提供一份使用文件讓使用者查看，API文件的呈現方式有很多種Markdown、Apiary，還有等等要介紹的Swagger…等
  • 撰寫這種文件需要花非常多時間，也必須制定出文件規範才能讓對接的使用者容易明瞭，這時候可以透過Swagger / OpenAPI來為我們產出文件
  • 使用者可以依照OpenAPI規範，將自己的 API 撰寫成YAML或者JSON檔案，再藉由swagger-ui轉換成一個 API 文件網頁。這個網頁可以部署在主機，或者放在專案中，需要的時候在 local 架起來檢視

Online Demo

  • 一開始在看的時候，完全看不懂，幸好他們有提供線上的editor demo，可以先從這個網站對照。
    Swagger-io
  • 畫面左方就是YAML檔案，而右方則是依照左方所渲染出來的 ui 頁面。頁面很清楚地列出 API 的description(描述)以及path(路徑)，點開之後可以看到更多API的資訊，像是接受什麼parameter(參數)，以及會有什麼response(回應)。而且使用者點擊try it out可以直接使用 API ，達到同時查看以及測試 API的效果

實作

  • 假定已經有基本的Django REST Framework專案，額外增加 Swagger
  1. 用 Django REST framework swagger 套件 drf_yasg 生成 Swagger UI
  • drf-yasg 是一個可以在 Django REST framework 自動生成 Swagger 的套件。我們先用 pip 安裝：
    1
    $ pip install drf-yasg

  1. 再將 drf_yasg 加到的 settings.py：

    1
    2
    3
    4
    5
    INSTALLED_APPS = [
      ...
      'drf_yasg',
      ...
    ]

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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    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'),
       ...
    ]

  3. 完成後透過指令啟動 server：

    1
    $ python manage.py runserver

    訪問 http://127.0.0.1:8000/swagger/ 就可以看到swagger UI
    Swagger-ui

Reference