はじめに

APIドキュメントをOpen API Specification v3（以下、OAS v３）形式で書く機会が増えてきました。
当記事では、OAS v３形式で書いたAPIドキュメントをgithubにプッシュするだけで自動デプロイして限られたメンバーで共有する方法を紹介します。

tl;dr

ボイラープレート（imunew/oas-boilerplate）を作ったので、そのポイントを解説します
swagpackにて、OAS v３形式のファイルを生成
swaggerapi/swagger-ui にて、Swagger-UIによるAPIドキュメントを生成
生成されたHTMLファイルをpublicディレクトリにて保持
publicディレクトリを含めてgithubにプッシュすると、CircleCI経由で、herokuにデプロイされる

ボイラープレートのディレクトリ構成

ディレクトリは以下のような感じです。
src配下のソースファイルがビルドされ、public配下にドキュメントが生成されます。

├── public
├── src
│   ├── components
│   │   ├── examples
│   │   │   └── index.yml
│   │   ├── schemas
│   │   │   └── index.yml
│   │   └── index.yml
│   ├── paths
│   │   └── index.yml
│   └── index.yml
├── Dockerfile
├── Makefile
├── Procfile
├── README.md
├── docker-compose.yml
├── oas-boilerplate.iml
├── package-lock.json
├── package.json
├── server.js
└── validate.js

`docker-compose.yml`、`Dockerfile`

ローカル環境は、docker-composeで構築しています。
以下、ポイントです。

swagpackを使って、src配下のymlファイルからapispec.ymlをビルド
swaggerapi/swagger-uiにて、Swagger-UIドキュメントを表示
出力されたHTMLファイルなどは、publicディレクトリに出力される

docker-compose.yml

version: '3'
services:
  swagger-ui:
    image: swaggerapi/swagger-ui
    ports:
      - 3020:8080
    volumes:
      - public_html:/usr/share/nginx/html/
    environment:
      API_URL: ./apispec.yml
    depends_on:
      - swagpack
  swagpack:
    build: .
    volumes:
      - ./src:/app/src
      - ./validate.js:/app/validate.js
      - public_html:/app/dist
    working_dir: /app

volumes:
  public_html:
    driver_opts:
      type: none
      device: $PWD/public
      o: bind

FROM node:10.15.1

WORKDIR /app

RUN yarn init -y
RUN yarn add swagpack@^0.0.5
RUN yarn add oas-validator
RUN yarn add js-yaml

CMD [ "yarn", "run", "swagpack", "build", "./src/index.yml", "-o", "/app/dist/apispec.yml", "-w", "./src" ]

`heroku`で動かすための設定

herokuの環境変数にて、BASIC認証のユーザー名（USER）とパスワード（PASS）を設定しておいてください。

あとは、heroku-static-providerを参考に、nodejsアプリとして、Swagger-UIを公開します。

package.json

{
  "name": "heroku-static-provider",
  "version": "0.0.1",
  "private": true,
  "dependencies": {
    "express": "^3.21.2"
  },
  "scripts": {}
}

server.js

var express = require('express');
var app = express();

var user = process.env.USER;
var pass = process.env.PASS;

app.set('port', process.env.PORT || 3000);

if (user && pass) {
  app.use(express.basicAuth(user, pass));
}

app.use(express.logger('dev'));
app.use(express.compress());
app.use(express.static(__dirname + '/public'));

app.listen(app.get('port'), function() {
  console.log('Server listening on port %s', app.get('port'));
});

// Profile
web: node server

`CircleCI`からのデプロイ

CircleCIの環境変数に以下の変数をセットしておいてください。

HEROKU_API_KEY: herokuのAPIキー
HEROKU_APP_NAME: herokuアプリの名前

あとは、下記の設定ファイルがあれば、任意のherokuアプリにソースがデプロイされ、publicディレクトリ以下が公開されます。

# .circleci/config.yml
version: 2
jobs:
  deploy:
    docker:
      - image: buildpack-deps:trusty
    steps:
      - checkout
      - run:
          name: Deploy master branch to heroku
          command: |
            git push https://heroku:$HEROKU_API_KEY@git.heroku.com/$HEROKU_APP_NAME.git master
workflows:
  version: 2
  build-deploy:
    jobs:
      - deploy:
          filters:
            branches:
              only: master

公開イメージ

デプロイされると、BASIC認証付きでアクセスできるようになります。
例えば、以下のようなイメージです。

URL: https://oas-boilerplate.herokuapp.com
BASIC認証: oas / oas

おわりに

OAS v３でAPIドキュメントを書いて、サーバー・クライアント間のコミュニケーションをスムーズにしましょう。
ではでは。