DRF勉強vol5_APIドキュメントの生成 #Django

はじめに

DRF(Django REST framework)の勉強のため、以下書籍を参考にサンプル作成します。
最終的には書籍にあるVue+DRFの作成を目指します。

現場で使えるDjangoの教科書
現場で使えるDjango REST Frameworkの教科書

Vol.4では別オリジンで動作するフロントエンド(Vue)からアクセスするためのCORS設定を行いました。
Vol.5ではOpenAPI形式のAPIのドキュメント生成をできるようにします。

環境

Intel Mac 13.4.1(c)
Python 3.11.4
Django 4.2.3
DRF 3.14.0

手順

drf-spectacularの導入

drf-spectacularパッケージを導入します。

$ poetry add drf-spectacular

この時点のpyproject.toml

[tool.poetry]
name = "backend"
version = "0.1.0"
description = ""
authors = ["Jozuo jozuo.dev@gmail.com"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.11"
django = "^4.2.3"
djangorestframework = "^3.14.0"
djangorestframework-simplejwt = "^5.2.2"
dj-rest-auth = "^4.0.1"
django-cors-headers = "^4.2.0"
drf-spectacular = "^0.26.4"

[tool.poetry.group.dev.dependencies]
debugpy = "^1.6.7"
pytest = "^7.4.0"
black = "^23.7.0"
ruff = "^0.0.280"
mypy = "^1.4.1"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

設定変更

設定ファイルに以下を追加します。

config/settings.py

  INSTALLED_APPS = [
      --- 省略 ---
      # 3rd party package
      "rest_framework",
      "rest_framework.authtoken",
      "dj_rest_auth",
      "corsheaders",
+     "drf_spectacular",
      --- 省略 ---
  ]
  
  --- 省略 ---

  REST_FRAMEWORK = {
      "DEFAULT_AUTHENTICATION_CLASSES": [
          "dj_rest_auth.jwt_auth.JWTCookieAuthentication",
      ],
+     "DEFAULT_SCHEMA_CLASS": "drf_spectacular.openapi.AutoSchema",
  }

ルート設定

ルート設定に以下を追加します。

config/urls.py

+ from django.conf import settings
  
  --- 省略 ---
  
+ if settings.DEBUG:
+     urlpatterns += [
+         path("api/schema/", SpectacularAPIView.as_view(), name="schema"),
+         path(
+             "api/schema/swagger-ui/",
+             SpectacularSwaggerView.as_view(url_name="schema"),
+             name="swagger-ui",
+         ),
+         path(
+             "api/schema/redoc/",
+             SpectacularRedocView.as_view(url_name="schema"),
+             name="redoc",
+         ),
+     ]

Swagger-UIでのAPI動作確認

ブラウザでhttp://localhost:800/api/scheme/swagger-ui/にアクセスするとAPIドキュメントが表示されます。
認証不要なAPIはこの状態で呼び出すことができますが、認証が必要なAPIは認証エラーになるため続けて認証の設定を行います。

JWTトークンの発行

Swagger-UIからPOST: /api/v1/login/エンドポイントを利用してJWTトークンを発行します。
以下のいずれかの組み合わせでAPIを実行します。

ユーザー名 + パスワード
メールアドレス + パスワード

ログインに成功すると、以下のようなレスポンスが表示されるため、accessの値をコピーします。

{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNjkwNTA1OTEwLCJpYXQiOjE2OTA1MDIzMTAsImp0aSI6IjQ3Y2JmYTYwYTU1NzQ5MzJiNDg2MmNiMWY1MzE2MTg5IiwidXNlcl9pZCI6MX0.kYB0PQgBZnWB-O0a1Y5Z5or--BPSEzeykA34pwdHN_8",
  "refresh": "",
  "user": {
    "pk": 1,
    "username": "admin",
    "email": "admin@example.com",
    "first_name": "",
    "last_name": ""
  }
}

JWTトークンの設定

Swagger-UI画面右上にある「Authorize」をクリックすると認証用ダイアログが表示されます。
このアプリケーションはヘッダー認証を利用しているためjwtHeaderAuth (apiKey)側するので、そちらのValueに "JWT [上で取得したトークン値]" を入力してAuthorizeを行います。

これで認証が必要なAPIもSwagger-UIから呼び出すことが可能になります。