GitLab Pagesで複数SwaggerUIを自動で公開する

こんにちは、開発部のomiです。
前回の投稿から7ヶ月が経っていてびっくりしました。絶対背が伸びたと思います。

今回は、現在携わっている新しいプロジェクトで導入した GitLab Pages について書きたいと思います。

経緯

今のプロジェクトではAPI設計にSwaggerを使用しました。

Swagger Specで書いた仕様は、最初はSwagger Codegenでhtml化し、毎回サーバにアップして公開していました。

修正の都度ローカルでhtml化し、サーバにアップする作業は面倒ですし、アップを忘れて仕様書と実装のずれが出てくる恐れもあります。

そこで、我がチームの頼れるリーダーイケマスこと池田さん lab.astamuse.co.jp に提案していただいた、GitLab Pagesでのhtml公開を行ってみることにしました。

↓GitLab Pages 公式 Document
GitLab Pages

手順

今回、この方の方法を真似してみることにしました。

gitlab.com

私たちのプロジェクトのSwagger Specは用途ごとに分かれており、それぞれを別のURLで同時に公開したかったので、少し工夫する必要がありました。
Swagger Specが一つだよ、という方は↑の方の設定のままで大丈夫です。

Projectの任意のフォルダにSwagger Specを配置する

project
.
├── README.md
├── api-docs
│   ├── api01
│   │   └── api01.yaml
│   ├── api02
│   │   └── api02.yaml
│   ├── api03
│   │   └── api03.yaml
│   ├── api04
│   │   └── api04.yaml
│   └── api05
│       └── api05.yaml

今回は api-docs というフォルダの下にyamlを配置しました。
先述の通りこのプロジェクトのSwagger Specは用途ごとに分かれていたのでそれぞれサブディレクトリに入れてあげる必要があります。

.gitlab-ci.yml に設定を記述する

.gitlab-ci.yml に以下の通り設定を記述します。

image: hseeberger/scala-sbt:8u181_2.12.6_1.2.3

variables:
    DOCS_FOLDER: "api-docs"

cache:
    paths:
        - ./node_modules

stages:
    - deploy

pages:
    image: node:10-alpine
    stage: deploy
    before_script:
        - npm install swagger-ui-dist@3.22.1
    script:
        - mkdir -p public
        - cp -rp $DOCS_FOLDER public/
        - cd public/$DOCS_FOLDER/
        - find . -mindepth 1 -type d -exec cp -p ../../node_modules/swagger-ui-dist/* {} \;
        - ls -1 | while read FILE ; do sed -i "s#https://petstore\.swagger\.io/v2/swagger\.json#${FILE}.yaml#g" ${FILE}/index.html ; done
    artifacts:
        paths:
            - public
    only:
        - develop

variables
Swagger Specを入れたフォルダを指定します。
pages:stage
html公開を走らせたいタイミング
pages:script
GitLabではpublicという名前のフォルダが公開対象と決まっているため、public配下にhtmlを配置してあげる必要があります。
DOCS_FOLDERで指定したSwagger Specを入れたフォルダをpublicフォルダにコピーし、各サブディレクトリ配下にswagger-ui-distフォルダをコピーします。
デフォルトでは公開するhtmlのurlがhttps://petstore.swagger.io/v2/swagger.json になっているので、ここをまるっとそれぞれのyaml / jsonの名前に変換します。
pages:artifacts
path:publicで生成されたジョブの成果物をジョブが成功した後にGitLabに送信します。

これが、developブランチのdeploy時に毎回走ることになります。

Swagger Specから生成されたhtmlが公開される

上記設定をしておくと、developブランチがdeployされたタイミングで

http://[Project].[GitLabのホスト]/[api-docsまでのパス]/api-docs/api01/

というようなURLでAPI仕様書が公開されます。

※イメージ

swagger-ui-image

最後に

今までの方法だとサーバ上のhtmlとプロジェクトにpushされているyamlの内容が食い違うというようなことが起こり得ていましたが、
今回の対応でyamlと公開されるhtmlが連動するようになり、yamlの管理も徹底されるようになったのでとても良い効果だと思いました。

弊社ではエンジニア・デザイナーを募集中です！興味を持っていただけましたらバナーからよろしくお願いします！
以上です。読んでいただきありがとうございました。