はじめに
どうも小野です。WebAPI仕様書の作成はどのようにしていますか？今回紹介するツール等がない時代はExcelを当たり前のように使っていたかもしれません。 Excelの場合、ファイルのバージョン管理に苦労することが多いため、効率がいいとは言えません。 そこで、今回はタイトルにもある通り、簡単３ステップでWebAPI仕様書を作成する方法をご紹介します。
前提
- Githubアカウントを登録済みであること
- Netlifyアカウントを登録済みであること
- Node.jsがインストールされていること
ステップ１ Githubセットアップ
リポジトリを新規作成します。
ステップ２ Netlifyセットアップ
Netlifyは静的サイトを公開できるホスティングサービスです。
ここでは公開するサイトを新規作成します。
ステップ３ 仕様書作成
ステップ１で作成したリポジトリからソースをダウンロードし、初期設定を行います。
git clone git@github.com:frevo-works/apisample.git cd apisample npm init npm i redoc-cli
redoc-cli は作成した YAML を HTML に変換してくれるツールで、Netlifyで公開するために必要です。 redocly.com
package.json を編集します。
// (省略)
"scripts": {
"build": "redoc-cli bundle swagger.yml -o dist/index.html", // 追加
"test": "echo \"Error: no test specified\" && exit 1"
},
// (省略)
swagger.yml を作成します。
openapi: "3.0.2"
info:
title: SampleAPI
version: "1.0"
paths:
/users:
get:
description: ユーザ一覧取得
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: number
description: ユーザID
name:
type: string
description: 氏名
email:
type: string
description: メールアドレス
以下のコマンドを実行して、仕様書を出力してみます。
npm run build
ビルドが完了すると、dist フォルダに index.html が出力されているのでブラウザで開きます。
正しく表示されたら、リモートリポジトリにプッシュします。
git add -A git commit -m "first commit" git push origin main
動作確認
Netlify を開き、以下のような状態になったら、表示されている URL をクリックします。すると、作成された API 仕様書が確認できます。
もし、閲覧制御等で API 仕様書のページに Basic 認証をかけたい場合、Netlify の有料プランに加入すると利用可能になります。
おまけ
効率よくYAMLファイルを編集する方法として２つご紹介します。
リアルタイムに確認する方法
編集中の内容をリアルタイムで確認できる方法として、Swagger Editor と、VSCode+Swagger のプラグインを利用する方法があります。 Swagger Editor は以下の リンク から起動することができます。
ただし、編集はブラウザ上で行うので、編集後はローカルのファイルに上書きする必要があります。 ローカルで Editor を起動する Docker もあるようですが、今回は後者の方法をご紹介します。
GUI で編集する方法
YAML ファイルを触りたくない人向けのツールをご紹介します。 このツールはGUI 上で設定、入力していくと最終的に YAML ファイルが出来上がる仕組みです。
おわりに
いかがでしたか？ツール等の導入には多少手間は必要ですが、Excelのひな型作成と考えればそこまでのコストはかからないと思います。 効率よくメンテンナンスを行うためにぜひ導入してみてください。 今回は紹介していませんが、仕様書を更新した際にSlackへ通知することも可能なので、興味がある方は調べてみてください。
