今回はDjango REST Framework(通称DRF)のAPI群をSwaggerに対応させます。
ただSwagger対応させる方法についてはいくつもの記事を読んできたが、認証・ログインが必要なAPIのSwagger対応をした記事がなかなか見つからなかったのでまとめてみた。(Swagger上で認証・ログインを行う事ができるようになります)
本記事の環境はDjango3.0系となっています
認証・ログインの必要なAPIをSwagger対応する
※もちろんAPIの作成は行っていること前提となります。serializers.pyやviews.pyにAPIの記述が既にあるものとします。
drf-yasgの導入
今回drf-yasgを使用する。(正直なんと読むのかは分からない..)
コマンド一発叩いておく
pip install drf-yasgちなみに、Documentはこちらから確認することが出来ます。
https://drf-yasg.readthedocs.io/en/stable/readme.html
(↑Django2.0系のドキュメントのため、Dnago3.0では若干仕様が異なります)
settings.py
drf-yasgを使うんだからsettings.pyに反映させないと。
INSTALLED_APPSに追加します。
INSTALLED_APPS = [
'channels',
'rest_framework',
'drf_yasg', # 追加
'myapps.apps.MyappsConfig',
'accounts.apps.AccountsConfig',
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
]urls.py
ルーティングの設定を行います。urls.pyに以下の記述を追加します
本記事では/api配下にswaggerのルーティング設定を記述しています。
from django.urls import path, re_path
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi
schema_view = get_schema_view(
openapi.Info(
title="Myapp API",
default_version='v1',
description="Test description",
terms_of_service="https://www.google.com/policies/terms/",
contact=openapi.Contact(email="hoge@hoge.jp"),
license=openapi.License(name="TEST License"),
),
public=True,
permission_classes=(permissions.AllowAny,),
)
urlpatterns = [
re_path( 'swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'), # Swagger-Editor用 json or yaml形式 ダウンロード
path( 'swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'), # Swagger-UI形式
path( 'redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'), # Redoc形式
]これだけ。以上
SwaggerでAPIを確認・実行
上記の設定を行いDjangoをlocalサーバーで立ち上げます
python manage.py runserverデフォルトですと以下のURLでSwaggerへアクセスできます
http://127.0.0.1:8000/swagger
こちらのSwagger画面にてAPIの仕様や実行の確認が行えます。
また、ログイン認証が必要なAPIについてはDjango Loginボタンを押すことでログインを行う事ができますので、ここで認証を行うことが出来ます。
(JWT認証の場合はAuthorizeボタンで認証可能です)
ログインすると(ログイン完了後、再度Swagger画面へ遷移すると)以下のようにログインユーザー情報が表示されるようになります。
ユーザー情報が表示されるようになればログイン認証完了です。
これで、ログインや認証の必要なAPIをSwagger上から実行することが可能です。
ログアウトを行う場合はDjango Logoutボタンとなります
jsonデータまたはyamlファイルとして出力も可能
上記で記載した、以下の部分で
urlpatterns = [
re_path( 'swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'), # Swagger-Editor用 json or yaml形式 ダウンロード
]APIをjson形式やyaml形式でダウンロードすることが出来ます。
実際にはhttp://127.0.0.1:8000/swagger.jsonにアクセスするとjsonデータを取得することができます。
http://127.0.0.1:8000/swagger.yamlでyaml形式でダウンロードすることが出来ます。
ここで取得したjsonデータやyamlファイルを共有することでAPIの仕様を他者へも共有することが可能です。
試しに出力されたyamlファイルを読み込んでAPIの仕様を確認してみます。
yamlファイルをダウンロード後にSwagger Editorから読み込みを行います。
上部のFile > Import Fileでダウンロードしたyamlファイルを選択します。
先程localサーバーでアクセスしたSwaggerのAPI仕様と同様のAPIを表示することが出来ました。
yamlファイルでAPI仕様の共有が簡単に出来ますね。
RedocでAPI仕様確認
http://127.0.0.1:8000/redocにアクセスするとredoc形式でAPIの確認も可能です。
こちらに慣れている方はこちらでも問題なさそうですね。(僕はこの形式はあまりしらない..)
drf-yasgを使用するとSwaggerのAPI管理が簡単ですね。
コメント