目的

django_restframeworkでAPIを作成していたが、APIはバックエンドとフロントエンドのインターフェースであり、フロント担当者が自分が作成したAPIをどのように扱えば良いのかすぐにわかるような状態にしなければそれはまともなAPIとは言えないのではないか。

と思い、簡単なものにはなるが、下の画像のようなAPIのドキュメントを作ってみることにした。

概要

DjangoRestframeworkにはAPIの定義書を(urls.pyから?)自動で作成してくれる素晴らしすぎる機能がある。

このAPI定義書があることによって開発担当者以外のエンジニアもAPIを簡単に利用することができるようになるのでとても大事。

正直手順自体は本当にびっくりするくらい簡単だった。

手順としては

YAML形式のデータを扱うためのライブラリ

URIを簡単に組み立てるためのライブラリ

$ pip install PyYAML==5.3.* uritemplate==3.0.*

スキーマをgenerateする。
ファイル名は自分で指定可能。

python manage.py generateschema --file APIschema.yml

vscodeの拡張機能から検索。

自動生成されたルートディレクトリにあるschema.ymlを選択した状態で、
shift + command + p(macの場合)でPreview Swaggerを選択

このようなAPI定義書が表示される。