Swagger x Heroku で手軽に API モック＆ドキュメントを作る

## 概要

Web、モバイル問わず、アプリケーション開発する際には、フロントエンドとバックエンド開発が一斉にスタートすることが多く、フロントエンド開発はバックエンド開発待ちになるケースがよくあります。この待ちの時に、フロントエンド側で仮で叩ける環境があると、実装をある程度進めることができ、開発が進みやすくなります。

この記事では Swagger と Heroku を用いて、 API のドキュメントとモック（スタブ）サーバーを手軽に作る方法を紹介します。

## Swagger って？

[Swagger](https://swagger.io/) は特定の書式で書くと API ドキュメントとかモックを良い感じで生成してくれるやつです。詳しい説明は公式ページをご参照ください。


## 手順

1. Swagger Editor で YAML 整形
- モック＆ドキュメントのサーバーサイドコードを Generate　する
- Heroku 用の修正をする
- Heroku にデプロイする
- もっと便利にする
  * クロスオリジン問題を解決 ( CORS 対応)
  * github に push したら Heroku にデプロイさせる
  * Basic 認証でアクセス制限をかける

## 1. Swagger Editor で YAML 整形

[Swagger Editor](https://editor.swagger.io/) で YAML を整形する。コードから書き出すライブラリもあるが、今回はエディタを使用する。また、ローカル環境で Swagger Editor を利用することもできる。

![スクリーンショット 2018-02-06 13.25.21.png](https://qiita-image-store.s3.amazonaws.com/0/19698/16abb49e-ee7d-1db1-f4dc-303d338c41fc.png)
Swagger Editor にアクセスしたら pet API のサンプルが表示されている。今回はこの API をそのまま利用。

## 2. モック＆ドキュメントのサーバーサイドコードを Generate　する

Swagger Editor 上で、 Generate Server > nodejs-server を選択する。こうするとサーバーサイドコードが zip ファイルでダウンロードできるので、ダウンロード後に解凍する。

![スクリーンショット 2018-02-06 13.27.10.png](https://qiita-image-store.s3.amazonaws.com/0/19698/498beaf3-8a46-a99b-0db2-c3741602b8f2.png)

## 3. Heroku 用の修正をする

serverPort の指定を編集する。これにより Heroku アップロード時に 80 番ポートでアクセスできる。

```JavaScript
- var serverPort = 8080;
+ var serverPort = process.env.PORT || 8080;
```

## 4. Heroku にデプロイする

Heroku に上げる。Heroku を使い慣れた方は、いつも通り heroku に git push。

```bash
$ git init
$ git add -A
$ git commit -am 'first commit'
$ git remote add heroku [heroku 指定の URL]
$ git push heroku master
```

やったことがない方は https://devcenter.heroku.com/articles/heroku-cli をご参照ください。

以上で Heroku にアクセスできる。ドキュメントは /docs/ でアクセスでき、 API のモックも立ち上がっている。

試しに作ったサンプルが以下。無料のやつなので 1 日の数時間は眠ってます :bow: 

- ドキュメント: https://api-doc-sample.herokuapp.com/docs/
- API: https://api-doc-sample.herokuapp.com/v2/pet/0

![スクリーンショット 2018-02-06 16.50.49.png](https://qiita-image-store.s3.amazonaws.com/0/19698/88e595d8-644d-dfd0-9d9d-ef597a6d4d6c.png)

![スクリーンショット 2018-02-06 16.50.54.png](https://qiita-image-store.s3.amazonaws.com/0/19698/b4bc606c-95b7-4f97-79ba-2ca9792323de.png)

画像は上がドキュメントの URL にアクセスしたもの。下が API の URL にアクセスしたもの。


## 5. もっと便利にする

### クロスオリジン問題を解決 ( CORS 対応)

Web アプリケーションの場合、クロスオリジン問題でモックを叩きづらいので CORS を有効にする。本当はモジュール入れずに対応したかったが、Swagger 本体のモジュールとの兼ね合いか、なぜか上手く設定できなかったので、 [cors](https://github.com/expressjs/cors) を利用する。

以下のコマンドを実行。

```bash
$ npm install cors --save
```

index.js を修正。

```JavaScript
  var app = require('connect')();
+ var cors = require('cors');

~

  swaggerTools.initializeMiddleware(swaggerDoc, function (middleware) {
+ 
+   app.use(cors());
```


### github 連携
heroku にそのまま git push するのではなく、 github でソースコード共有したい場合、 github に push したタイミングで heroku にデプロイする設定にしておくと良い。

https://dashboard.heroku.com/apps からアプリケーションを選択し、 Deploy メニューから Github を選択して設定する。

### アクセス制限をかける

Node.js の [basic-auth-connect](https://github.com/expressjs/basic-auth-connect) パッケージを追加して、 Basic 認証をかけることができる。

以下のコマンドを打つ。

```bash
$ heroku config:set BASIC_AUTH_USERNAME="hello"
$ heroku config:set BASIC_AUTH_PASSWORD="world"
```

package.json の dependencies に basic-auth-connect を追加。

```JSON
  "dependencies": {
+     "basic-auth-connect": "*",
```

index.js に処理を追記

```JavaScript
  var serverPort = process.env.PORT || 8080;
+ var basicAuth = require('basic-auth-connect');
+
+ var username = process.env.BASIC_AUTH_USERNAME;
+ var password = process.env.BASIC_AUTH_PASSWORD;
+
+ if (username && password) {
+   app.use(basicAuth(username, password));
+ }
```

これで起動するとこんな感じでちゃんとユーザー名とパスワード聞かれる。今回は

- ユーザー名: hello
- パスワード: world

![スクリーンショット 2018-02-06 16.55.32.png](https://qiita-image-store.s3.amazonaws.com/0/19698/416ae1c8-c492-3c37-23ad-4a7dd97040ae.png)

サンプルはこちら

- ドキュメント: https://api-doc-sample-basic-auth.herokuapp.com/docs/
- API: https://api-doc-sample-basic-auth.herokuapp.com/v2/pet/0

## その他の Tips

### AWS API Gateway の利用

AWS の API Gateway も Swagger に対応している。詳しくは https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/create-api-using-swagger.html 参照。 aws コマンドからもアップロードできるらしい。

### 好みの Editor で編集して、 モックのコードを生成する

swagger-codegen を使えば、swagger.yml からソースコードを生成できるらしい。
https://github.com/swagger-api/swagger-codegen

### 毎回 index.js ファイルや package.json ファイルが更新されるのを防ぐ

swagger.yml を更新する度に、普通にソースコード生成すると index.js や package.json も更新される。github 連携していたら gitignore したいところだが、リポジトリにあがったファイルは gitignore できないようなので、以下のコマンドで無視する。

```bash
$ git update-index --assume-unchanged index.js
$ git update-index --assume-unchanged package.json
```

参考: [既に git 管理しているファイルをあえて無視したい](https://qiita.com/usamik26/items/56d0d3ba7a1300625f92)

### 環境を自分で作りたくない場合は SwaggerHub

[SwaggerHub](https://swaggerhub.com/) を使えば Swagger Editor のような UI で、ドキュメントとモックが自動的に生成される。ただ、無料でできることがほとんどなく、有料プランは結構お高め。

## まとめ

以上、かなり手軽に API モック＆ドキュメントを作ることができました。まだ調べ始め・触り始めなので、もっと良い方法などありましたらコメントください！