Zenn
🐍

【Django】Django REST FrameworkでSwagger（OpenAPI）を導入して、API仕様書を作成する

に公開
Django
Python
API
Swagger
DRF
tech

完成図


Swaggerの画面


Redocの画面

drf-yasgをインストール

requirements.txt
drf-yasg==1.21.7　# JSON形式、YAML形式でのAPI仕様書を自動生成してくれる
djangorestframework==3.14.0

settings.pyにdrf-yasgを追加

settings.py
INSTALLED_APPS = [
    'drf_yasg',
    'rest_framework',
]

settings.pyにSwaggerとDRFの設定を追加

settings.pyへの追記
# REST Framework設定
REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework_simplejwt.authentication.JWTAuthentication',
        'rest_framework.authentication.SessionAuthentication',
    ],
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.IsAuthenticated',
    ],
    'DEFAULT_RENDERER_CLASSES': [
        'rest_framework.renderers.JSONRenderer',
    ],
    'DEFAULT_PARSER_CLASSES': [
        'rest_framework.parsers.JSONParser',
        'rest_framework.parsers.MultiPartParser',
    ],
}

# Swagger用の設定を追加
SWAGGER_SETTINGS = {
    'SECURITY_DEFINITIONS': {
        'Bearer': {
            'type': 'apiKey',
            'name': 'Authorization',
            'in': 'header',
            'description': 'JWT Authorization header using the Bearer scheme. Example: "Bearer {token}"'
        }
    },
    'USE_SESSION_AUTH': False,
    'JSON_EDITOR': True,
    'SUPPORTED_SUBMIT_METHODS': [
        'get',
        'post',
        'put',
        'delete',
        'patch'
    ],
}

urls.pyにSwaggerのURLパターンを追加

urls.py
from django.urls import path, include, re_path # re_pathを用いるとURLを正規表現(柔軟なURL指定)が可能。
from drf_yasg.views import get_schema_view　# Swagger UI 用のビューを作る関数
from drf_yasg import openapi
from rest_framework import permissions # DRFの認可（パーミッション）機能.APIドキュメントが誰に公開されるかをコントロールするために使う。 

# Swagger設定
schema_view = get_schema_view(
    openapi.Info(　# 以下の情報は、Swagger UIの画面上部に「このAPIはこういうものです」と表示される。
        title="API",
        default_version='v1',
        description="API仕様書",
        terms_of_service="https://www.---.com/terms/",
        contact=openapi.Contact(email="contact@---.com"),
        license=openapi.License(name="Private License"),
    ),
    public=True,
    permission_classes=(permissions.AllowAny,),
    authentication_classes=[],
)

urlpatterns = [
# Swagger UI
    re_path(r'^swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'),
    path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
    path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),　# redocは、Swagger UI よりシンプルな見た目で、API仕様を読むのに適している。
]
APIメモ

・APIは一般にHTTPリクエスト/レスポンスのやりとりで動く。
・どんなエンドポイントまたはパラメータを渡すのかを一覧（API仕様書）にすると便利。
・手書きでこれをまとめたものが「APIドキュメント」だが、ミスが発生するのを避けるため、標準的なものが作成された。
・標準フォーマットにしたのがOpenAPI Specification (OAS)。である
・OpenAPI形式のAPI仕様 = APIの構造・入力・出力・説明などを 機械可読な JSON / YAMLファイル にまとめたもの。
・Swagger UI = それをきれいに「画面表示」してくれるツール。
・drf-yasg のようなツールを使うとDjangoのAPIエンドポイントを自動でスキャンしてSwagger / OpenAPI形式 の仕様ファイル（JSON/YAML）を自動で生成しSwagger UI画面にリアルタイムで表示することができる。
・特にオープンAPIを公開する時は YAML が一般的。

図解
Django REST Framework の API実装
          ↓
   drf-yasg が API構造を解析
          ↓
OpenAPI Specification (JSON / YAML形式) を自動生成
          ↓
Swagger UI がそれを画面に表示 (Swagger / Redoc)

【応用】APIテスト実装時

JWTトークンを生成する



Try it out➡ ログインのmailとPassを入力 ➡ Exetuteを押す ➡ JWTトークンを生成する

JWSを使用しない場合のAuthorize認証


Authorizeをクリックしてユーザーでログインする

JWTトークンを設定


JWTトークンをSwagger上部のAuthorizeのBearer認証フィールドに先ほど取得したaccessトークンを入力する

Bearer認証

- Bearer認証
・OAuth 2.0で広く使用されているHTTP認証スキーム。
・トークンベースの認証方式で、トークンをHTTPヘッダに含めてリクエストすることでユーザーの認証・認可を行う。
・「デジタル署名による改ざん検知」と「パスワードの非送信」が主なセキュリティメリット。

【応用】API仕様書の表示

JSON形式：
http://localhost:8000/swagger.json
YAML形式：
http://localhost:8000/swagger.yaml
Redoc形式（きれいなドキュメント）：
http://localhost:8000/redoc/

Discussion