APIスキーマを生成するdrf-spectacular

1カ月ぶりでございます。萬木大志です。

今回は、Djangoで実装したAPIのスキーマを自動で生成するdrf-spectacularについての記事となっております。

背景

現在、DjangoによるAPIの実装しており、徐々に実装してきたAPIが増えてきたため、フロント部分との連携テストなどでフロント側で使用する機会が出てきました。そのため、APIを利用する人に対して「どのようなAPIがあるのか」、「どのようなリクエストを送るのか」、「レスポンスはどのようなものなのか」などの情報が記載されたドキュメントが必要になってきたためです。

drf-spectacularとは

DjangoによるAPI開発で用いられるライブラリ、Django REST Framework(DRF)には、APIスキーマを出力するgenerateschemaコマンドが標準で備わっています。このコマンドで生成したAPIスキーマファイルをSwagger UIなどに読み込ませることで、API利用者に読みやすい仕様書を作ることができます。しかし、この方法では、既存APIの変更や新しくAPIを実装する度にgenerateschemaコマンドを打ち、APIスキーマファイルを生成しなければなりません。DRFの公式サイトでは、APIスキーマに関するページ(https://www.django-rest-framework.org/topics/documenting-your-api/)にこの標準機能の他にいくつかのサードパーティのパッケージを勧めており、その中の1つが今回使用しているdrf-spectacularです。drf-spectacularは、OpenAPI 3に準拠したAPIスキーマを生成し、拡張性やカスタマイズ性、実際にAPIを送信することができるAPIクライアント生成に重きを置いたAPIドキュメンテーションパッケージとなっています。APIスキーマの出力はもちろんのこと、Swagger UIのデザインとReDocデザイン、二種類のAPIドキュメント画面を自動で生成してくれるなんとも便利なパッケージです。

導入方法

手順は公式のドキュメントかgithubのREADMEに書いている通りです。まず、パッケージのインストールをします。

$ pip install drf-spectacular

次に、DRFのプロジェクトディレクトリにあるsettings.py内の INSTALLED_APPSREST_FRAMEWORKに以下の行を追加します。

INSTALLED_APPS = [         
    `drf-spectacular`,    # 追加
]
...
REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',  # 追加
}

同じsettings.py内でAPIドキュメントのタイトル、ドキュメント全体に関する説明文、ドキュメントのバージョン も設定できます。

# 全行追加
SPECTACULAR_SETTINGS = {
    'TITLE': 'Your Project API',
    'DESCRIPTION': 'Your project description',
    'VERSION': '1.0.0',
}

また、APIドキュメント画面を自動生成するために、プロジェクトのURLconfに次の設定を書き加えます。

from drf_spectacular.views import SpectacularAPIView, SpectacularRedocView, SpectacularSwaggerView # 追加
...
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'), # 追加
]

このURLの設定をそのまま使用した場合、runserverコマンドでプロジェクトを起動させて、http://localhost:8000/api/schema/swagger-ui/にアクセスすると、Swagger UIデザインのAPIドキュメント画面が表示されます。

また、http://localhost:8000/api/schema/redoc/にアクセスすると、ReDocデザインのAPIドキュメント画面が表示されます。

簡単なカスタマイズ

ここまでの作業だけで、ViewSet、ModelViewSetなどは提供されているアクション(listやcreateなど)や入出力のパラメタなどは自動で表示されます。しかし、デフォルトの設定だけでは基本的なAPIの表示しか行われないため、基本的にはカスタマイズをする必要があります。例えば、APIに簡単な説明を追加したい場合には、該当のViewSetクラスに@extend_schema_viewを使います。

@extend_schema_view( # 追加部分始
    list=extend_schema(description='ユーザの一覧取得'),
    create=extend_schema(description='ユーザの作成'),
    retrieve=extend_schema(description='指定したユーザの情報の取得'),
    update=extend_schema(description='指定したユーザの更新(更新には全情報が必要)'),
    partial_update=extend_schema(description='指定したユーザの一部更新(更新したいパラメタのみ渡してもOK)'),
    destroy=extend_schema(description='指定したユーザの削除(使用しないこと)'),
)  # 追加部分終
class UserViewSet(viewsets.ModelViewSet):
    ...

また、リクエストのサンプルデータはデフォルトの場合、サンプルとしてはあまり適さないものとなっています。

そのため、先ほどの@extend_shcema_view部分に以下の内容を追加します。

@extend_schema_view(
    list=extend_schema(description='ユーザの一覧取得'),
    create=extend_schema(
        description='ユーザの作成',
        examples=[                        # 追加部分始
            OpenApiExample(
                '入力例1',
                summary='A社の田中太郎',
                description='存在しない会社のUUIDを入力したら作成できないので注意してください!',
                value={
                    'name': '田中太郎',
                    'email': 'tanakatarou@gmail.com',
                    'phone_num': '09012345678',
                    'send_email_notification': False,
                    'company': '4533a69e-9e29-4961-bef6-f0d7bddb95be',
                },
            ),
        ],
    ), # 追加部分終
    retrieve=extend_schema(description='指定したユーザの情報の取得'),
    update=extend_schema(description='指定したユーザの更新(更新には全情報が必要)'),
    partial_update=extend_schema(description='指定したユーザの一部更新(更新したいパラメタのみ渡してもOK)'),
    destroy=extend_schema(description='指定したユーザの削除(使用しないこと)'),
)
class UserViewSet(viewsets.ModelViewSet):
...

Swagger UI画面を開いてみると、

作成したサンプルデータはそのままAPIクライアントで実際にテストが行えるためぜひ試してみてください!今回、紹介したdrf-spectacularは、拡張性、カスタマイズ性に優れたパッケージであるため、この方法よりも適した書き方があるかもしれません。ぜひ興味を持ちましたら公式サイトを参考に使ってみましょう!

FIXER Inc. 萬木 大志
  • FIXER Inc. 萬木 大志
  • はじめての一人暮らしいつ生活習慣が崩れるのか怯えています