drf-yasg で生成した swagger ドキュメントにレスポンスクラスを表示するハック

こんにちは！フルサポート開発チームの高畑（@int_sorarinu）です。

最近お休みの日は雪山に篭りがちで、先日の 3 連休のうち 2 日連続でスノボへ行ったら身体が痛すぎて使い物にならなくなっていました。最近は翌日以降に筋肉痛が襲ってくるようになりちょっとだけ悲しい気持ちになっています。

ビザスクでは日々 Python + Django で開発を行っており、これまでは django-rest-swagger のリポジトリを fork してレスポンスクラスが表示されるように魔改造した所謂「オレオレ swagger」を利用して API ドキュメントの生成を行っていました。

しかし、django-rest-swagger は既にリポジトリがアーカイブ・非推奨となっているため、今動いているシステムリプレースのタイミングで drf-yasg へ置き換えがされました。

今回は、drf-yasg で生成される swagger ドキュメントへ Django のレスポンスクラスが表示されるようにする方法をご紹介します。

そもそも drf-yasg って？

drf-yasg は django-rest-swagger の代替として利用されることが多いオープンソースの swagger ジェネレータです。

Python + Django の環境で利用ができ、OpenAPI 2.0 に準拠した swagger ドキュメントを生成することができます。

https://github.com/axnsan12/drf-yasg

swagger ドキュメントにレスポンスクラスを表示させる

drf-yasg で生成される swagger ドキュメントの中身をカスタマイズするためには、OpenAPISchemaGeneratorを継承した独自クラスを定義する必要があります。

import rest_framework.permissions
from django.urls import include, path
from drf_yasg import openapi
from drf_yasg.generators import OpenAPISchemaGenerator
from drf_yasg.views import get_schema_view


class CustomSchemaGenerator(OpenAPISchemaGenerator):
    def get_operation(self, view, path, prefix, method, components, request):
        operation = super().get_operation(
            view,
            path,
            prefix,
            method,
            components,
            request,
        )

        module_name = view.__module__
        class_name = view.__class__.__name__
        function_name = view.action if hasattr(view, "action") else ""

        operation.description = """
### Response Class : {module_name}.{class_name}#{function_name}
---
{description}
""".format(
            module_name=module_name,
            class_name=class_name,
            function_name=function_name,
            description=operation.description,
        )

        return operation


schema_view = get_schema_view(
    openapi.Info(
        title="API Docs",
        default_version="v1",
        description="API Docs powered by OpenAPI",
    ),
    public=True,
    authentication_classes=[rest_framework.authentication.SessionAuthentication],
    permission_classes=[rest_framework.permissions.AllowAny],
    generator_class=CustomSchemaGenerator,
)

urlpatterns = [
    path(
        "",
        schema_view.with_ui("swagger", cache_timeout=0),
        name="schema-swagger-ui",
    ),
]

OpenAPISchemaGenerator.get_operation()をオーバーライドすることで、独自の付加情報を swagger ドキュメントへ表示することができるようになります。

おわりに

いかがだったでしょうか。

社内限定で公開している swagger ドキュメントであれば、レスポンスクラスなどの付加情報を表示することでルーティングからコードを追いかける必要がなくなり開発業務が行いやすくなるのではないでしょうか！