Django REST Framework で API ドキュメンテーション機能を利用する方法（DRF 3.12 最新版）

DRF 3.12 の状況

現在の最新バージョンの DRF 3.12で OpenAPI 3.0 に準拠した API スキーマを出力する方法として、筆者は次の二つの方法を推奨します。ひとつは DRF 標準の generateschema コマンドを使って OpenAPIスキーマファイルを出力する方法、もうひとつは 「drf-spectacular」というサードパーティ製パッケージを使う方法です。*1

ちなみに、DRF で API スキーマを出力するにはこれまで「CoreAPI」ベースの「rest_framework.schemas.coreapi.AutoSchema」を使うのがデフォルトだったのですが、これは DRF 3.10 で非推奨になり、DRF 3.12 以降で削除予定となっています。*2
なおこの記事を書いている時点ではまだ削除はされていないようですが、今後いつ削除されるとも分かりません。

Django REST Framework v3.10 でネイティブな OpenAPI ベースのスキーマ生成が導入されたことにより、CoreAPI ベースのスキーマの使用は非推奨となりました。

Django REST Framework v3.12 で CoreAPI 関連のコードはすべて削除されます。それまでに OpenAPI スキーマに切り替えてください。

（https://www.django-rest-framework.org/coreapi/の内容を抜粋して翻訳）

本記事では、DRF 3.12 で OpenAPI 3.0 に準拠した API スキーマを出力する方法として

• 【方法１】generateschema コマンドを使って OpenAPIスキーマファイルを出力する方法
• 【方法２】drf-spectacular を利用する方法

について紹介します。

導入方法

導入方法はほぼ 公式ドキュメントに書いてある通りです。

まず、drf-spectacular をインストールします。*4

(venv) > pip install drf-spectacular==0.11.*

次に、設定ファイルの「INSTALLED_APPS」に「drf_spectacular」を追加し、「REST_FRAMEWORK」の「DEFAULT_SCHEMA_CLASS」に「drf_spectacular.openapi.AutoSchema」を設定します。

config/settings.py（設定ファイル）

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',

    # 3rd party apps'drf_spectacular',  # 追加

    ...
]

...

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',  # 追加
}

OpenAPI スキーマファイルを出力するだけなら設定はここまでで OK です。コマンドプロンプトから spectacular コマンドを使えば、API スキーマファイルを出力することができます。

(venv) > python manage.py spectacular --file schema.yml

APIドキュメント画面を自動生成したいのであれば、続けて URLconf に次の設定を書き加えます。ちなみに、DEBUG が False の場合にのみ APIドキュメント画面を表示できるようにしています。

config/urls.py（URLconf）

from django.urls import include, path
from drf_spectacular.views import SpectacularAPIView, SpectacularRedocView, SpectacularSwaggerView  # 追加

urlpatterns = [
    ...（略）...
]

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ドキュメント画面

設定完了後に runserver を起動し、（起動 URL が「127.0.0.1:8000」の場合）ブラウザで「http://127.0.0.1:8000/api/schema/swagger-ui/」にアクセスすれば、Swagger UI 形式の APIドキュメント画面が表示できます。

API ごとの「Try it out」ボタンをクリックして、「Parameters」を適宜入力して「Execute」ボタンをクリックすることでリクエストを送信することができるので、API クライアントとしても利用することができます。

ReDoc 形式の APIドキュメント画面

ReDoc 形式の APIドキュメント画面（http://127.0.0.1:8000/api/schema/redoc/）は次のようになります。

カスタマイズ

これでよいかと思いきや、ちょっとしたカスタマイズが必要な箇所もあります。

例えば、ListAPIView や RetrieveAPIView などの汎用 APIView 系ビューや ModelViewSet 系ビューなど（クラス変数 serializer_class を指定するもの）は入出力のパラメータが自動判定されるのですが、APIView を継承しているビューではドキュメンテーションが不完全になります。その場合は、extend_schema でドキュメンテーション用の追加設定をしてあげる必要があります。

apiv0/views.py（ビュー）

from drf_spectacular.utils import extend_schema
from rest_framework import status, views
from rest_framework.response import Response

from shop.models import Book
from .serializers import BookSerializer


classBookListCreateAPIView(views.APIView):
    """本モデルの取得（一覧）・登録APIクラス"""@extend_schema(
        responses={200: BookSerializer},
    )
    defget(self, request, *args, **kwargs):
        """本モデルの取得（一覧）APIに対応するハンドラメソッド"""

        ...（略）...

        return Response(serializer.data, status.HTTP_200_OK)

    @extend_schema(
        request=BookSerializer,
        responses={201: BookSerializer},
    )
    defpost(self, request, *args, **kwargs):
        """本モデルの登録APIに対応するハンドラメソッド"""

        ...（略）...

        return Response(serializer.data, status.HTTP_201_CREATED)

他にもいろいろ追加設定ができますが、詳細については公式ドキュメントを参照してください。

Settings — drf-spectacular documentation