Help us understand the problem. What is going on with this article?

Open API Specification (OAS) をCircleCI経由でherokuにデプロイする

はじめに

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

tl;dr

  • ボイラープレート(imunew/oas-boilerplate)を作ったので、そのポイントを解説します
  • swagpackにて、OAS v3形式のファイルを生成
  • 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.ymlDockerfile

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

photocreate
ITの力で、写真を通じて感動があふれかえる社会を実現する「フォトライフ構想」を目指すWebサービスを展開しています
https://www.photocreate.co.jp/
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした