drf-spectacular

drf-spectacular は、Django REST Framework (DRF) 用の OpenAPI Schema 生成ツールで、OpenAPI 3.0 および 3.1 をサポートします。

その主な機能は、Serializer、View、URL、Authentication および DRF のその他の情報に基づいて OpenAPI ドキュメントを自動的に生成することであり、開発者がデコレータや拡張メカニズムを通じて自動的に推論できないコンテンツを補足できるようにします。

一般的なワークフロー:

Django Model / Serializer / View
                ↓
          drf-spectacular
                ↓
          OpenAPI Schema
                ↓
       ┌────────┴────────┐
       ↓                 ↓
   Swagger UI           Orval
                         ↓
                TypeScript Types
                Axios / Query Hooks

1. 基本構成と自動推論

基本構成

# settings.py

INSTALLED_APPS = [
    "rest_framework",
    "drf_spectacular",
]

REST_FRAMEWORK = {
    "DEFAULT_SCHEMA_CLASS":
        "drf_spectacular.openapi.AutoSchema",
}

SPECTACULAR_SETTINGS = {
    "TITLE": "Example API",
    "DESCRIPTION": "Example API Documentation",
    "VERSION": "1.0.0",
}

Schemaを自動生成

最も基本的なケースでは、通常、追加の drf-spectacular コードは必要ありません。

from rest_framework import serializers
from rest_framework.generics import RetrieveAPIView


class UserProfileSerializer(serializers.Serializer):
    name = serializers.CharField()
    avatar = serializers.URLField(allow_null=True)


class UserProfileView(RetrieveAPIView):
    serializer_class = UserProfileSerializer
    queryset = User.objects.all()

drf-spectacular は、serializer_class に基づいて応答構造を自動的に推測できます。

responses:
  "200":
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/UserProfile"

主な依存関係を自動的に推測します。

• serializer_class / get_serializer_class()
• queryset
• get_serializer()
• Viewタイプと対応するHTTP動作
• DRF の認証、ページング、フィルター構成

GenericAPIView、RetrieveAPIView、ListAPIView、ModelViewSet は、一般に、裸の APIView よりも自動的に推論するのが簡単です。

注: APIView.get() 内で Serializer を呼び出すだけでは、drf-spectacular が Serializer を自動的に認識できるわけではありません。

2. @extend_schema

@extend_schema は、drf-spectacular で最も一般的に使用されるデコレーターであり、自動的に推論された情報を補足またはオーバーライドするために使用されます。

from drf_spectacular.utils import extend_schema


@extend_schema(
    request=UsernameUpdateSerializer,
    responses={200: UserProfileSerializer},
)
def patch(self, request):
    ...

以下に対応します:

PATCH Request Body
        ↓
UsernameUpdateSerializer

HTTP 200 Response
        ↓
UserProfileSerializer

共通パラメータ

原則: 自動推論を優先し、推論が間違っている、または推論できないコンテンツに対してのみ @extend_schema を使用します。

3. GET Parameters および POST Request Body

GET リクエストは通常、Query Parameters を使用します。

@extend_schema(
    parameters=[SearchPoiSerializer],
    responses=SearchPoiResponseSerializer,
)
def get(self, request):
    ...

以下に対応します:

GET /api/v1/pois?name=Tokyo&limit=10

POST リクエストは通常、Request Body を使用します。

@extend_schema(
    request=SearchPoiSerializer,
    responses=SearchPoiResponseSerializer,
)
def post(self, request):
    ...

以下に対応します:

POST /api/v1/pois/search
Content-Type: application/json

{
  "name": "Tokyo",
  "limit": 10
}

違い

注:

• POST は Query Parameters を持つこともできます。
• GET 通常、Request Bodyは使用しません。
• parameters は、Query パラメータを記述する OpenApiParameter または Serializer のいずれかに渡すことができます。
• request は通常、Serializer、基本タイプ、またはプリミティブ Schema 定義で渡されます。

4. OpenApiParameter

リクエストパラメータを明示的に記述するために使用されます。

from drf_spectacular.utils import (
    OpenApiParameter,
    OpenApiTypes,
)

Queryパラメータ

@extend_schema(
    parameters=[
        OpenApiParameter(
            name="keyword",
            type=OpenApiTypes.STR,
            location=OpenApiParameter.QUERY,
            required=True,
            description="Search keyword",
        ),
        OpenApiParameter(
            name="limit",
            type=OpenApiTypes.INT,
            location=OpenApiParameter.QUERY,
            required=False,
            default=20,
        ),
    ]
)
def get(self, request):
    ...

以下に対応します:

GET /api/v1/search?keyword=tokyo&limit=20

Pathパラメータ

OpenApiParameter(
    name="poi_id",
    type=OpenApiTypes.INT,
    location=OpenApiParameter.PATH,
    required=True,
)

以下に対応します:

GET /api/v1/pois/123

Path パラメータは必須である必要があります。

Headerパラメータ

OpenApiParameter(
    name="X-Request-ID",
    type=OpenApiTypes.STR,
    location=OpenApiParameter.HEADER,
)

対応するリクエスト:

X-Request-ID: abc-123

応答 Header

OpenApiParameter は、response パラメータ記述を介した Header への応答もサポートします。

OpenApiParameter(
    name="Retry-After",
    type=OpenApiTypes.INT,
    location=OpenApiParameter.HEADER,
    response=[429],
    description="Retry delay in seconds",
)

次に、@extend_schema(parameters=[...]) を渡します。

説明されている内容は次のとおりです。

HTTP/1.1 429 Too Many Requests
Retry-After: 35

クライアントによって送信されたリクエスト Header の代わりに。

5. ResponsesとOpenApiResponse

ステータスコードに基づいて応答を定義する

@extend_schema(
    responses={
        200: UserProfileSerializer,
        400: ValidationErrorSerializer,
        401: AuthenticationErrorSerializer,
        429: RateLimitErrorSerializer,
    }
)
def get(self, request):
    ...

さまざまな HTTP ステータス コードに対応する応答構造体が生成されます。

OpenApiResponse

OpenApiResponse では、応答の説明と例をさらに追加できます。

from drf_spectacular.utils import OpenApiResponse


@extend_schema(
    responses={
        200: OpenApiResponse(
            response=UserProfileSerializer,
            description="User profile retrieved",
        ),
        404: OpenApiResponse(
            response=ErrorSerializer,
            description="User not found",
        ),
    }
)
def get(self, request):
    ...

応答本文のない操作の場合:

@extend_schema(
    responses={
        204: OpenApiResponse(
            response=None,
            description="Successfully deleted",
        )
    }
)
def delete(self, request):
    ...

複数のメディアタイプ

@extend_schema(
    responses={
        (200, "application/json"): UserSerializer,
        (200, "application/pdf"): OpenApiTypes.BINARY,
    }
)
def get(self, request):
    ...

Schema は、メディア タイプごとに個別に指定できます。

実際には、インターフェイスごとにすべてのエラー ステータス コードを機械的に繰り返す必要はありませんが、クライアントが処理する必要がある重要なエラー応答がドキュメントに含まれていることを確認する必要があります。一般的なエラーは、公開ツールまたはプロジェクト レベルのメカニズムを通じて均一に管理できます。

6. @extend_schema_view

@extend_schema_view は、クラスレベルで複数のメソッドをまとめて記述するために使用されます。

from drf_spectacular.utils import (
    extend_schema,
    extend_schema_view,
)


@extend_schema_view(
    get=extend_schema(
        responses=UserProfileSerializer,
    ),
    patch=extend_schema(
        request=UserProfileUpdateSerializer,
        responses=UserProfileSerializer,
    ),
    delete=extend_schema(
        request=None,
        responses={204: None},
    ),
)
class UserProfileView(GenericAPIView):
    ...

それぞれ get()、patch()、delete() に @extend_schema を加算した場合と同等の効果があります。

ViewSet の場合、Action 名が必要です。

@extend_schema_view(
    list=extend_schema(tags=["Users"]),
    retrieve=extend_schema(tags=["Users"]),
    create=extend_schema(tags=["Users"]),
)
class UserViewSet(ModelViewSet):
    ...

これは、DRF Mixin が継承され、操作メソッドの明示的なオーバーライドがないシナリオに特に適しています。

7. @extend_schema_field

カスタム Serializer Field の場合、drf-spectacular の戻り値の型が正確に推論されない可能性があります。

たとえば:

class CoordinatesField(serializers.Field):
    def to_representation(self, value):
        return [value.longitude, value.latitude]

次のものが使用できます。

from drf_spectacular.utils import extend_schema_field


@extend_schema_field({
    "type": "array",
    "items": {"type": "number"},
    "minItems": 2,
    "maxItems": 2,
})
class CoordinatesField(serializers.Field):
    ...

以下に対応します:

type: array
items:
  type: number
minItems: 2
maxItems: 2

これは、座標配列の長さを制限するため、単に ListField(FloatField()) を宣言するよりも明示的です。

注: 上記の構造は OpenAPI 内の長さ 2 の数値配列を表しますが、TypeScript コード ジェネレーターは必ずしもそれを固定長タプル [number, number] として認識するとは限らず、number[] を生成する場合もあります。

8. SerializerMethodField

SerializerMethodField の場合は、型アノテーションまたは @extend_schema_field を使用して戻り値の型を明示することをお勧めします。

class UserSerializer(serializers.Serializer):
    display_name = serializers.SerializerMethodField()

    @extend_schema_field(serializers.CharField())
    def get_display_name(self, obj):
        return obj.name.upper()

Python タイプも使用できます。

@extend_schema_field(str)
def get_display_name(self, obj):
    return obj.name.upper()

単純な型の場合は、明示的な戻り型の注釈でも十分な場合があります。

def get_display_name(self, obj) -> str:
    return obj.name.upper()

複雑なオブジェクト、リスト、または入れ子構造が返される場合は、Serializer 記述を明示的に使用することをお勧めします。

9. @extend_schema_serializer

これは、元のノートに追加する価値のある一般的なデコレータです。

@extend_schema_serializerはSerializer全体のSchemaの性能を調整するために使用します。

たとえば:

from drf_spectacular.utils import extend_schema_serializer


@extend_schema_serializer(
    exclude_fields=("internal_note",),
)
class UserSerializer(serializers.Serializer):
    id = serializers.IntegerField()
    username = serializers.CharField()
    internal_note = serializers.CharField()

Schema を生成する場合、internal_note は無視されます。

注: これは Schema ドキュメントにのみ影響し、DRF Serializer によって実際に出力されるデータは自動的に変更されません。

Envelope構造

一部の API は統合応答にラップされています。

{
  "success": true,
  "data": {
    "id": 1,
    "username": "Alice"
  }
}

応答 Serializer は明示的に定義できます。

class UserResponseSerializer(serializers.Serializer):
    success = serializers.BooleanField()
    data = UserSerializer()

多数の統合パッケージ構造がある場合は、extend_schema_serializer、動的 Serializer ファクトリー、またはプロジェクト レベルの拡張機能を使用して、Schema 定義をさらに再利用できます。

10. inline_serializer

構造が単純で一度だけ使用される応答の場合、別個の Serializer クラスを定義する必要は必ずしもありません。

from drf_spectacular.utils import inline_serializer


@extend_schema(
    responses=inline_serializer(
        name="HealthResponse",
        fields={
            "status": serializers.CharField(),
            "version": serializers.CharField(),
        },
    )
)
def get(self, request):
    ...

以下に対応します:

{
  "status": "ok",
  "version": "1.0.0"
}

該当するシナリオ:

• Health Check。
• 単純なステータス応答。
• 1 回限りの小さなデータ構造。

同じ構造が複数のインターフェースで繰り返し現れる場合でも、再利用と保守を容易にするために独立した Serializer を定義することをお勧めします。

11. OpenApiExample

OpenApiExample は、リクエストまたはレスポンスに例を追加するために使用されます。

from drf_spectacular.utils import OpenApiExample


@extend_schema(
    request=UsernameUpdateSerializer,
    examples=[
        OpenApiExample(
            name="Username Update",
            value={
                "username": "alice"
            },
            request_only=True,
        ),
    ],
)
def patch(self, request):
    ...

一般的に使用されるパラメータ:

たとえば、200 応答の例を追加します。

OpenApiExample(
    name="Success",
    value={
        "id": 1,
        "username": "alice",
    },
    response_only=True,
    status_codes=["200"],
)

この例では、実行時に返されたデータは自動的に検証されず、インターフェイスのドキュメントと関連ツールの表示にのみ使用されます。

12. ファイルアップロードとOpenApiRequest

ファイルアップロードインターフェースの場合、multipart/form-dataの記述が必要です。

Serializer

class AvatarUploadSerializer(serializers.Serializer):
    avatar = serializers.ImageField()

View

from rest_framework.parsers import MultiPartParser
from drf_spectacular.utils import OpenApiRequest


class AvatarUploadView(GenericAPIView):
    parser_classes = [MultiPartParser]

    @extend_schema(
        request={
            "multipart/form-data": OpenApiRequest(
                request=AvatarUploadSerializer,
            )
        },
        responses={200: AvatarResponseSerializer},
    )
    def post(self, request):
        ...

通常、OpenAPI ファイルのフィールドは次のとおりです。

type: string
format: binary

次の点に注意する必要があります。

• parser_classes は、DRF が実際にサポートするリクエスト データ解析方法を決定します。
• @extend_schema はインターフェイス コントラクトを記述する責任があります。
• Schema 定義では、View ファイルのアップロード処理機能が自動的に付与されません。

リクエストとレスポンスのフィールド表現が異なる状況では、次のことを考慮してください。

SPECTACULAR_SETTINGS = {
    "COMPONENT_SPLIT_REQUEST": True,
}

これは、リクエストとレスポンスの FileField、読み取り専用フィールド、必須フィールドなどの違いをより正確に記述するのに役立ちますが、生成される Schema コンポーネントの数が増加する可能性があります。

13. Authentication Extension

カスタム認証メカニズムの場合、drf-spectacular は自動的に認識されない場合があります。

次のものが使用できます。

from drf_spectacular.extensions import (
    OpenApiAuthenticationExtension,
)

たとえば:

class BrowserSessionAuthenticationScheme(
    OpenApiAuthenticationExtension
):
    target_class = (
        "myapp.authentication.BrowserSessionAuthentication"
    )
    name = "browserSession"

    def get_security_definition(self, auto_schema):
        return {
            "type": "apiKey",
            "in": "cookie",
            "name": "sorivel_session",
        }

OpenAPIに対応：

components:
  securitySchemes:
    browserSession:
      type: apiKey
      in: cookie
      name: sorivel_session

ここで定義されるのは、認証資格情報がどのように渡されるかです。

Extension は認証ロジックを自動的に実装せず、CSRF 保護も実装しません。

実際の認証ロジックは依然として DRF Authentication Class の責任です。

カスタム認証は通常、Extension を使用してプロジェクト レベルで均一に記述するのに適しており、View ごとにステートメントを繰り返す必要はありません。

14. その他 Extension

drf-spectacular は、自動推論の動作を変更するためのさまざまな Extension を提供します。

Extension は通常、次の目的で使用されます。

• サードパーティのライブラリ。
• パブリック基本クラス。
• デコレータコードを直接追加することはできません。
• プロジェクト内で均一に扱う必要があるカスタム コンポーネント。

Extension レジスタ

Extension クラスは、Schema が生成される前に Python によってインポートされる必要があります。

以下に配置できます:

myapp/
├── apps.py
├── schema.py
├── serializers.py
└── views.py

次に、apps.py にインポートします。

class MyAppConfig(AppConfig):
    name = "myapp"

    def ready(self):
        import myapp.schema  # noqa: F401

このようにして、drf-spectacular が Schema を生成すると、対応する Extension が見つかります。

15. Postprocessing Hook

Postprocessing Hook は、OpenAPI Schema が完全に生成された後、結果を均一に変更するために使用されます。

def postprocess_contract(
    result,
    generator,
    request,
    public,
):
    # 変更 OpenAPI Schema
    return result

構成:

SPECTACULAR_SETTINGS = {
    "POSTPROCESSING_HOOKS": [
        "drf_spectacular.hooks.postprocess_schema_enums",
        "common.api.schema.postprocess_contract",
    ],
}

注: POSTPROCESSING_HOOKS をリセットすると、デフォルト設定が上書きされます。

デフォルトの Enum 処理を維持する必要がある場合は、以下を明示的に追加する必要があります。

"drf_spectacular.hooks.postprocess_schema_enums"

代表的な用途

• 生成されたoperationIdを変更します。
• 一部の Schema の統一メタデータを補足します。
• コンポーネントの名前や参照を調整します。
• 一般的な応答構造を変更します。
• コードジェネレータが互換性のない特殊な Schema を処理します。

Preprocessing Hook

Preprocessing Hook は Postprocessing とは異なり、Schema が生成される前に実行され、主に生成されるインターフェイス リストの処理に使用されます。

たとえば:

SPECTACULAR_SETTINGS = {
    "PREPROCESSING_HOOKS": [
        "drf_spectacular.hooks.preprocess_exclude_path_format",
    ],
}

組み込みの Hook は、DRF format suffix によって生成された重複したパスを削除できます。

原則: Serializer を最初に表現できる場合は、Serializer を使用します。 extend_schema を表現できますが、extend_schema を最初に使用する必要があります。 Hook は主にグローバル Schema 変換を処理します。

16.カスタムAutoSchema

drf-spectacular はデフォルトで以下を使用します。

drf_spectacular.openapi.AutoSchema

基礎となる推論動作は、継承を通じて変更できます。

from drf_spectacular.openapi import AutoSchema


class ApiAutoSchema(AutoSchema):
    ...

一般的な用途には次のようなものがあります。

• カスタム Operation ID 世代。
• パラメータの推論を変更します。
• 応答構造の推論を変更します。
• 認定要件を変更するための推論。

Operation ID をカバーする例:

class ApiAutoSchema(AutoSchema):
    def get_operation_id(self):
        operation_id = super().get_operation_id()
        return operation_id

実際のプロジェクトでは、内部推論メソッドを勝手に上書きすることは避けるようにしてください。このようなカスタマイズは drf-spectacular の実装内容と強く結びついており、バージョンアップ時に互換性の再検証が必要になるためです。

17. operationId

各 OpenAPI Operation には一意の operationId が必要です。

たとえば:

operationId: getUserProfile

Orval などのコード生成ツールは通常、それに基づいて API 関数または Hook を生成します。

getUserProfile();
useGetUserProfile();

正確な名前はコード生成構成によって異なります。

手動で指定する

@extend_schema(
    operation_id="getUserProfile",
)
def get(self, request):
    ...

自動生成

drf-spectacular は、URL メソッドや HTTP メソッドなどの情報に基づいて Operation ID を自動生成できます。

たとえば:

/api/v1/users/profile/
      ↓
users_profile_retrieve

手動による仕様が必要かどうかは、プロジェクトの要件によって異なります。

• 内部 API、統一命名規則: 最初に自動生成。
• フロントエンド SDK をリリース: 長期的な安定性のために Operation ID を維持することをお勧めします。
• 自動生成された名前は不明瞭であるか矛盾していますが、手動で指定できます。

Orval の場合、operationId の変更により生成される関数名が変更される可能性があり、その結果フロントエンド コードに影響を与える可能性があります。

18. Tags

Tags はインターフェイスのグループ化に使用されます。

@extend_schema(
    tags=["Users"],
)
def get(self, request):
    ...

Swagger UI と ReDoc は通常、Tags 表示インターフェイスに従ってグループ化されます。

Orval:

mode: "tags-split";

結果の API ファイルは、Tags に基づいて分割することもできます。

したがって、Tags はドキュメントの表示に影響を与えるだけでなく、フロントエンドで生成されたコードのディレクトリ構造にも影響を与える可能性があります。

ビジネス モジュールには、次のような Tag という統一された名前を採用することをお勧めします。

Users
POI
Itinerary
Authentication

19. よく使われるSPECTACULAR_SETTINGS

ほとんどのプロジェクトでは、すべての構成を変更する必要はありません。

最初はデフォルト設定を保持し、実際の問題にのみ調整することをお勧めします。

20. Schemaの生成とCIの検証

Schema を生成する

python manage.py spectacular \
    --file openapi.yaml \
    --validate \
    --fail-on-warn

パラメータ:

• --file: 出力ファイル。
• --validate: 生成された OpenAPI Schema を確認します。
• --fail-on-warn: Schema 生成警告が表示されるとコマンドが失敗します。

区別する必要があります:

• Schema 検証: 文書構造が OpenAPI 仕様に準拠しているかどうかを検証します。
• API テスト: 実際のインターフェイスが期待どおりに動作することを確認します。
• TypeScript Typecheck: フロントエンド呼び出しコードのタイプが正しいかどうかを確認してください。

これら 3 つは互いに代替できるものではありません。

CI/CDプロセス

変更 Django API
        ↓
      pytest
        ↓
spectacular --validate
        ↓
   生成する openapi.yaml
        ↓
       Orval
        ↓
TypeScript Typecheck
        ↓
   Build / Deploy

CI で早めに調べてください:

• Schema が正しく生成できません。
• Serializer フィールドが変更されます。
• Operation ID が変わります。
• 生成された TypeScript タイプは、既存のコードと互換性がありません。
• API Client の生成に失敗しました。

ただし、フロントエンドとバックエンドが異なるウェアハウスにある場合は、Schema を同期する方法と、どのウェアハウスで Orval を実行するかを知っておく必要があります。

21. よくある質問と実践原則

Schema が間違ったタイプを生成するのはなぜですか?

よくある理由:

• カスタム Serializer Field は自動的に推論できません。
• SerializerMethodField タイプ情報がありません。
• View は Serializer を宣言していません。
• 実際の Response の構造は Serializer と矛盾します。
• カスタム認証またはページング メカニズムが認識されません。

生成された YAML を直接変更するのではなく、対応する Serializer、View、または Field に正確な情報を補足することを優先する必要があります。

インターフェイスごとに extend_schema を記述する必要がありますか?

不要。

DRF 自体の定義が十分に明確であれば、drf-spectacular は大量の Schema 情報を自動的に生成できます。

推奨される拡張子の優先順位

DRF 自然な定義
       ↓
Serializer / GenericAPIView
       ↓
@extend_schema
       ↓
@extend_schema_field
@extend_schema_serializer
       ↓
Extension
       ↓
Pre/Postprocessing Hook
       ↓
カスタマイズ AutoSchema

これはエンジニアリング上の選択順序であり、フレームワークの義務ではありません。

通常、後退するほどカスタマイズ機能が向上し、メンテナンス コストも増加する可能性があります。

概要

drf-spectacular の重要な機能は 4 つのカテゴリに分類できます。

通常の Django REST Framework プロジェクトの場合、最もよく知っておく必要があるのは以下の内容です。

1. 自動推論を備えた serializer_class。
2. @extend_schemaと@extend_schema_view。
3. parameters、request、responses。
4. @extend_schema_field。
5. operation_idとTags。
6. Schema の検証とクライアント コードの生成。

プロジェクトにカスタム認証、複雑な応答ラッパー、サードパーティ Serializer Field、または統合 Schema 変換要件が含まれている場合は、Extension、Hook、およびカスタム AutoSchema を再度検討してください。

---

参考資料

• drf-spectacular Documentation
• Schema Customization
• Settings Reference
• drf-spectacular API Reference
• OpenAPI Specification