APIドキュメント (Swagger UI)
Swagger UIとは
Swagger UIとは、APIのテストと仕様の文書化のためのツールです。
詳しく
Web APIを呼び出して実行するには本来、このように「ターミナル」という黒い画面からよくわからないコマンドをたたく必要があったのですが、
同じAPIの呼び出しがこのようにGUIで分かりやすく簡単にできます。
また複数人で開発する際には、開発者間でAPIの仕様や使い方を共有する必要があります。
しかし、コンピュータ向けのAPIのプログラムを書いたうえで、さらに人間用に使い方のドキュメントも書かなければいけないのは大変ですよね。
ですが、星陵祭オンライン整理券システムで採用しているFastAPIは、ソースコードを書くと、Swagger UIのドキュメントを自動で生成してくれます！
APIドキュメントへのアクセス
「(APIサーバーのURL)/docs」でアクセスできます。
開発環境：api-dev.seiryofes.com/docs
APIドキュメントの使い方
例として本番環境の画面を使います。
右上のAuthorize
認証を行います。
詳しく
【工事中】
また、未認証など、必要な権限が満たされていない場合、このようなレスポンスとなります。
左のGETやPOST
リクエストの分類のことです。
- GET…データを取得すること
- POST…書き込み操作を行うこと(≒データを作成すること)
- PUT…更新すること
- DELETE…削除すること
これは、団体一覧を取得するGETメソッドのメニューです。
左上の/groups
エンドポイントです。
Redisキャッシュについては【工事中】
必要な権限
GETメソッドには基本的に必要な権限はありません。
Responses
結果の例が並べられています。
右のTry It Out
メソッドを実行することです。
詳しく
Executeを押すことで実行できます。
下にはその結果(Server response)が帰ってきます。
ステータスコードも同時に帰ってきます。
今度は団体を追加するPOSTメソッドのメニューです。
左上の/groups
エンドポイントです。
必要な権限
この場合、Adminの人間が前述のAuthorizeを行うことで実行できるようになります。
権限について詳しくは【工事中】
下のRequest Body
多くのPOSTメソッドは、Try It Outの際に、
例えば「どのような団体を作成するのか」など、リクエストの内容を記述する必要があります。
詳しくは【工事中】