Django Rest Frameworkを使って爆速でAPIドキュメントを作成する
どこかで見たことがあるタイトルですねー
それは置いておいて、今回はDjango Rest Frameworkを利用して超お手軽&便利なAPIドキュメントを作成する方法のご紹介。
Django Rest Framework
Django Rest FrameworkはDjangoでweb APIを作ると言えばこれ！！
と言うぐらい有名なライブラリなのであまり説明はしませんが、超便利なライブラリです。
Rest FrameworkはAPIを簡単に作れることに注目されがちですが、実はAPIドキュメントも簡単に作ることができます。
APIドキュメントを作成する
Web APIを作るときは、ドキュメントも用意しておかないと使う人が使いづらいのできっと用意することでしょう。
でも、ドキュメント書くのって結構面倒なんですよね。
しかし、Django Rest Frameworkはそれさえも簡単に作成できます。
Django Rest Framework v3.6より追加された標準の機能を利用して作成していきます。
事前準備
APIは事前に作成されていると仮定します。
また、Django Rest Frameworkの他にちょっとだけ追加でライブラリが必要なのでインストールします。
pip install coreapi
以下の二つはなくても動作しますが見た目が少し綺麗になるので入れることをお勧めします。
pip install Pygments Markdown
いざ、爆速で実装する
追記するのは3行だけです。urls.pyのファイルに追記します。
from rest_framework.documentation import include_docs_urls # 追記
urlpatterns = [
...
path('docs/', include_docs_urls(title='My API title')) # 追記
]
これだけでAPIドキュメント完成です！
3行もいらなかったですね、2行だけでした。
では、早速ブラウザでアクセスしてみてください。
APIを試す
こんなに簡単に作成できたAPIドキュメントですが、実はAPIを実際に呼び出して試す事も出来るんです。
APIの開発中はPOSTMANを利用する人も多いと思いますが、わざわざそんなものを使わなくても、APIドキュメントだけで完結します。
さらには認証が必要なAPIも左下の項目に必要なパラメータを入力しておくだけで、認証済みの通信もできます。
さすが、組み込みの機能って感じです。
エラーがでた
docs/にアクセスして確認してみると
AttributeError: 'AutoSchema' object has no attribute 'get_link'
と表示されエラーになることがあります。
DRF 3.10以上だと発生するエラー
3.10 Announcementによるとdrf3.10からはSchema生成にCoreAPIからOpenAPIを用いるようになり、将来的にはバージョン3.12でCoreAPIはDRFから削除される方針らしいです。
OpenAPIのかわりにCoreAPIをつかうためにはsettings.pyに以下を書き加えます。
REST_FRAMEWORK = {
...
'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema'
}
さいごに
以上、簡単にDjango Rest Frameworkで爆速でAPIドキュメントを作成する方法をご紹介しました。
参考
https://www.django-rest-framework.org/coreapi/from-documenting-your-api/#built-in-api-documentation