SwaggerとGitLab Runnerを使ってAPIモックサーバーを起動する

GitLab RunnerとSwaggerを使って、OpenAPI形式のAPI仕様書をGitLabにpushしたら、API仕様書通りのモックサーバーがデプロイされる仕組みを作ります。

構成
前提
手順
確認
まとめ
参考

構成

今回構築する環境は以下の通りです。

API仕様書をGitLabにpushしたら、GitLab Runnerを使ってAPIモックサーバー(Swagger)を起動する環境。

実現したい一連の流れは以下の通りです。

API仕様書をGitLabにpush
パイプラインを作成
GitLab Runnerが実行
Dockerホスト上にAPIモックサーバー(Swagger)を起動

前提

GitLabサーバーが構築済み
GitLabサーバーにGitLab Runnerを登録済み

GitLabサーバー＋GitLab Runnerの環境構築手順は以下を参考にしてください。

手順

プロジェクトフォルダを作成し、作成したフォルダに移動します。

$ mkdir api-doc
$ cd api-doc

Docker Composeの設定

docker-compose.ymlを作成します。

swagger-editor:
  image: swaggerapi/swagger-editor
  container_name: "swagger-editor"
  ports:
    - "8001:8080"
swagger-ui:
  image: swaggerapi/swagger-ui
  container_name: "swagger-ui"
  ports:
    - "8002:8080"
  volumes:
    - ./api:/api/
  environment:
    SWAGGER_JSON: /api/openapi.yml
    # API_URL: ""
swagger-api:
  image: danielgtaylor/apisprout
  container_name: "swagger-api"
  ports:
    - "8003:8000"
  volumes:
    - ./api:/api/
  command: /api/openapi.yml

APIモックサーバーとして動作するswagger-api(apisprout)に加えて、Swagger Editor, Swagger UIを使って仕様書を作成・確認できるようにしています。

ポートは8001~8003をマッピングしているので、すでに利用中の場合は別のポートを指定してください。

GitLab CICDの設定

次に、.gitlab-ci.ymlを作成します。

before_script:
  - docker info
  - apk update
  - apk upgrade
  - apk add py-pip
  - apk add python-dev libffi-dev openssl-dev gcc libc-dev make
  - pip install docker-compose
build:
  tags:
    - docker  # specify tag of your gitlab runner
  script:
    - docker-compose down
    - docker-compose up -d
    - docker cp ./api/openapi.yml swagger-ui:/api/
    - docker-compose restart

buildのtagsには、Swaggerを起動させたいGitLab Runnerのタグを指定してください。

後ほど作成するopenapi.ymlを読み込んで、swaggerをコンテナ上で起動するようになっています。

Open API仕様の作成

最後に、APIの設計書を作ります。

今回は、getHelloという”Hello Open API.”という文字列を返すAPIを作ってみます。

$ mkdir api/

api/openapi.ymlに以下を記述します。

openapi: 3.0.0
info:
  title: Sample API
  description: example of CICD.
  version: 1.0.0
servers:
  - url: http://api.example.com/v1
    description: Specify the URL of the Docker host GitLab Runner runs.
paths:
  /message:
    get:
      summary: Returns message with string.
      description: Returns "Hello Open API."
      responses:
        '200':
          description: A message of hello open api.
          content:
            application/json:
              schema: 
                type: string
                example: "Hello Open API."

/messageにアクセスすると、”Hello Open API”という文字列を返します。

それでは、これをGitLabへpushして、APIモックサーバーが起動してみましょう。

git init
git remote add origin ssh://git@[GitLabのURL]/api-doc.git
git add .
git commit -m "Initial commit"
git push -u origin master

パイプラインが起動されて、ビルドが始まります。

確認

Swagger Editor

http://{DockerホストのURL}:8001でアクセスできます。

Swagger UI

http://{DockerホストのURL}:8002でアクセスできます。

APIモックサーバーの確認

APIモックサーバには、http://{DockerホストのURL}:8003でアクセスできます。

以下のようにcurlでリクエストを飛ばしてみましょう。

$ curl http://{DockerホストのURL}:8003/message
Hello Open API.

上記のように、”Hello Open API”が返ってくれば、正しく環境が構築できています。

まとめ

いかがでしょう、GitLab、GitLab RunnerとSwaggerを組み合わせることで、API仕様書をpushするだけで、Web上でAPIドキュメントが公開され、さらに仕様書通りに動作するAPIモックサーバーも起動することができました。

フロントエンドとバックエンドの開発におけるドキュメントのやり取りや、API仕様に対する認識の祖語など、多くの問題を劇的に改善してくれると思います。

APIドキュメントの運用に悩んでる方、ぜひ試してみてはいかがでしょうか。

同様の技術で、Webアプリケーションを自動デプロイする方法も紹介しているので、ご参考になれば幸いです。

参考

Open APIの基本構成

Basic Structure