目的
django_restframeworkでAPIを作成していたが、APIはバックエンドとフロントエンドのインターフェースであり、フロント担当者が自分が作成したAPIをどのように扱えば良いのかすぐにわかるような状態にしなければそれはまともなAPIとは言えないのではないか。
と思い、簡単なものにはなるが、下の画像のようなAPIのドキュメントを作ってみることにした。
概要
DjangoRestframeworkにはAPIの定義書を(urls.pyから?)自動で作成してくれる素晴らしすぎる機能がある。
このAPI定義書があることによって開発担当者以外のエンジニアもAPIを簡単に利用することができるようになるのでとても大事。
正直手順自体は本当にびっくりするくらい簡単だった。
手順としては
1. pip install PyYAML==5.3.* uritemplate==3.0.*でPyYAML,uritemplateをインストール
2. python manage.py generateschema --file schema.ymlでOpenAPIスキーマファイルの自動生成を実行
3. VsCodeの拡張機能のSwagger Viewerをインストールする
4. Swagger Viewerで自動生成されたOpenAPIスキーマファイル(yaml)を確認する
というものだ。
方法
PyYAML,uritemplateをインストール
PyYAML
YAML形式のデータを扱うためのライブラリ
uritemplate
URIを簡単に組み立てるためのライブラリ
$ pip install PyYAML==5.3.* uritemplate==3.0.*
OpenAPIスキーマファイルの自動生成を実行
スキーマをgenerateする。
ファイル名は自分で指定可能。
python manage.py generateschema --file APIschema.yml
Swagger Viewerをインストール
vscodeの拡張機能から検索。
OpenAPIスキーマファイル(yaml)を確認
自動生成されたルートディレクトリにあるschema.ymlを選択した状態で、
shift + command + p(macの場合)でPreview Swaggerを選択
このようなAPI定義書が表示される。
参考文献
OpenAPI Document の自動生成
Django REST Framework で API ドキュメンテーション機能を利用する方法（DRF 3.12 最新版）