Swagger(OpenAPI Specification: OAS)を使ったWebAPI設計の手順

はじめに

APIエコノミーが盛り上がっています。例えばTwitterのようにツイートデータを公開したり、Googleのように画像処理や自然言語処理の技術を公開するのにWebAPIが使われています。
他には、障害に強いサービスを作るためにアーキテクチャをモノリシックからマイクロサービスに移行する動きがあり、マイクロサービス間はWebAPIで繋がっています。
現代においてWebAPIは必要不可欠なインターフェースであり、だからこそWebAPIの設計は非常に綿密に行う必要があります。

今回は、Swaggerを利用したWebAPIの設計方法についてまとめました。

目次

  1. 1. APIを設計する前にRestful WebAPIの基礎を学ぶ
  2. 2. 仕様を考える
  3. 3. 詳細設計をする
  4. 4. コーディング
  5. 5. APIを試用する
  6. おわりに

1. APIを設計する前にRestful WebAPIの基礎を学ぶ

下記は良書なので購入して一読してください。基礎を知ることで、誰にとっても使いやすいWebAPIを設計することができます。
逆に言えば、基礎を知ることなく「俺が考えた最強のWebAPI」を作ると、誰にとっても使いづらいWebAPIができることでしょう。

Web API: The Good Parts
https://www.oreilly.co.jp/books/9784873116860/

2. 仕様を考える

APIを設計&実装する前に、まずは全体設計を行います。

「システムはいくつのサブシステムで構成するか」「各サブシステム間をモノリシックに作るか、あるいはマイクロサービスで疎結合にするか」「各サブシステムはどんな情報をやり取りするか」など、できる限り詳細にシステム全容を設計します。

仕様策定の段階では、どのようなツールを使っても良いと思います。私はwikiにまとめることが多いですが、メモ帳やWordでも構わないです。ちなみに、既に脳内に明確な仕様が設計できているのであれば、本作業は必要ありません。

私の場合、UIを伴うWebサービスを作るときには、まず画面遷移図を作成します。「各画面で何を描画するか」「画面間の遷移をどうするか」をPowerPointを使って画像で設計します。
この作業を行うことで、「各画面で必要な情報は何か?」「画面遷移の時に必要な情報は何か?」「遷移先の画面のURLをどう設計するか」が明確になります。

3. 詳細設計をする

システムにどのようなAPIが必要かを検討します。

例えば、「マイクロサービス間の情報のやりとり」「UIの描画に必要な情報」「データの登録・変更・削除に必要な情報」など、連携するシステムや機能毎に必要な情報を明記していきます。

情報の整理は、Step1で学んだRestful(GET/POST/PUT/DELETE)な視点を用います。例えば、「任意IDのデータの取得」と「任意IDのデータの削除」は同じAPIエンドポイントでGET/DELETEを使い分けることで実現できます。
詳細設計の際、情報の整理は手書きのメモでもWordでもwikiでも構いません。

4. コーディング

Step3の仕様書に基づき、実際にコーディングします。

ここからは好みが大きいと思いますが、私はコーディングする際はコードからswagger spec(※)を自動生成できる開発言語とライブラリを選択します。

例えば、JavaであればSpring BootでWebAPIを作り、SpringFoxでSwagger specを自動生成します。
PythonであればDjangoでWebAPIを作り、Django REST SwaggerでSwagger specを自動生成します。

あるあるですが、コーディングをしていると「ここはひとつにまとめられる」「ここはAPIを分けたほうがよい」など、改善点がいくつか見つかる場合があります。
このとき、コードからSwagger specを生成できるライブラリを利用していると、API仕様書を修正する作業が不要となり、開発が加速します。
また、常に最新のAPI仕様を確認できるため、例えば「フロントエンド x バックエンド開発」や「関連サービスとの連携」など複数人が関わる作業が加速します。

ちなみに、今更ですが現在はSwaggerとは呼ばずOpenAPI specificationと呼びます。

5. APIを試用する

OpenAPI (旧Swagger) を利用するメリットとして、Swagger UIを利用できる点があります。

Swagger UIは開発したWebAPIを試用できるインターフェースです。APIを利用する側にSwagger UIのURLを教えることで、気軽にAPIの入出力を確認できます。

個人的には、Swagger UIは画像処理や自然言語処理、統計処理など情報処理を行うサービスのAPIに採用するのが良いと思います。情報処理系のAPIは「使ってみるまで何ができるのか利用者がイメージしづらい」ことがしばしばあります。

利用者の裾野を広げるために、気軽に試せるSwagger UIのような枠組みは効果的だと思います。

おわりに

以上で、WebAPIの設計方法について説明を終わります。

何事でもそうですが「基礎を学び」「全体を俯瞰した上で」「詳細を詰めていく」作業がWebAPIの設計においても非常に重要です。
Restful WebAPIの基礎を学び、システムの全体像をイメージしたあとで、各サブシステムの詳細設計を行うことで、誰にとっても使いやすいWebAPIを設計することができます。
実装時にSwaggerを利用することで、試して使えるWebAPIを関連サービスやエンジニアに提供することが出来ます。

参考になれば幸いです。

(※)Swagger spec・・・Swagger仕様に準拠したJSON/YAML形式で記述する仕様書。