はじめに
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ドキュメントを書いて、サーバー・クライアント間のコミュニケーションをスムーズにしましょう。
ではでは。