More than 1 year has passed since last update.

SwaggerドキュメントのHTML化するGitlab-runnerを作る話

Posted at 2022-11-08

APIドキュメントってどうしていますか？
私はいままでwikiでぽちぽちやっていましたが…
めんどくさいですしメンテが大変なんですよ！
しかも、ブランチで作っている新機能を反映させたりすると…
悲惨です。ブランチ単位にファイルがある方がメンテナンスが楽だと最近気づきまいた。
ファイルだったら何があるかな？と思いまして今回はSwaggerを使うことにしました！
しかしながら、swaggerはyaml(もしくはjson)形式…
可読性が低いです。読みやすいようにHTML化出来るツールがあります。
なのでプッシュタイミングでHTML化してやろうと思ったわけです

APIドキュメント書くならSwagger

… Swaggerとは…

APIドキュメント作成用記述ファイル書式です。

詳しくは… : https://swagger.io/

要するにこんなドキュメントが描けるようになります！

Swaggerファイルはこんな感じです(抜粋)

  /searchItems :
    post :
      summary: キーワードを指定して検索します
      parameters:
        - in: "body"
          name: "body"
          required: true
          schema:
            $ref: "#/definitions/SearchItemsRequest"
      responses:
        '200':
          description: 実行結果
          schema:
            $ref: "#/definitions/SearchItemsResponse"
...
  SearchItemsRequest:
    type : object
    properties:
      keyword :
        type : string
        example: 4047306290
  SearchItemsResponse:
    type : object
    properties:
      status:
        type: integer
        example: 200
      message:
        type: string
        example: null
      items:
        type: array
        items:
          $ref: "#/definitions/Item"
  Item :
    type : object
    properties:
      asin :
        type : string
        example: 459216024X
      title :
        type : string
        example: 3月のライオン 14 (ヤングアニマルコミックス)
      url :
        type : string
        example: https://www.amaz...
      img_src :
        type : string
        example: https://ws-fe.amaz...

読めないので、今回スクリプトを使ってHTMLに出力させます。
するとこんな感じです。

SwaggerをHTML変換するのはredoc-cliを使う

HTML化するにはredocを使いました。

使い方はシンプルです

#redoc-cli build ./documents/API.yaml -o ./documents/API.html

./documents/API.yamlにswaggerファイルを配置していて
出力するHTMLファイルを./documents/API.htmlに出力します

Redoc-cliのGitlab-runnerを作る

HTMLファイルの作成のコマンドが決まりましたのでこれをプッシュされると実行するGitlab-runnerを作成します。

redoc-cliはnpmパッケージですのでnpmのgitlab-runnerを作ります。
詳細は前回の記事にて参考ください
https://www.mmpp.org/archives/3089

wataru@gitlab:~$ sudo docker run -d --name gitlab-runner-npm-report --restart always -v /var/run/docker.sock:/var/run/docker.sock  gitlab/gitlab-runner:latest
47394e7e62a62f7e265c0041e920ef0808a358a78d6d6c390d7b451f0823f00c
wataru@gitlab:~$ sudo docker exec -it gitlab-runner-npm-report /bin/bash
root@47394e7e62a6:/# apt-get update
root@47394e7e62a6:/# apt-get install xz-utils
root@47394e7e62a6:/# wget https://nodejs.org/dist/v18.12.0/node-v18.12.0-linux-x64.tar.xz
root@47394e7e62a6:/# tar -C /usr/local --strip-components 1 -xJf node-v18.12.0-linux-x64.tar.xz
 
root@47394e7e62a6:/# node -v
v18.12.0
root@47394e7e62a6:/# npm -v
8.19.2

はい、node v18が入りましたので次にredocをインストールしてやります

root@47394e7e62a6:/# npm install -g redoc-cli
root@47394e7e62a6:/# redoc-cli --version
0.13.20

これでHTMLの作成できる環境は完成しました

Gitlab-runnerに登録する

次にGitlab-runnerに作成したGItlab-runnerを登録します

root@47394e7e62a6:/# gitlab-runner register
Runtime platform                                    arch=amd64 os=linux pid=323 revision=4b9e985a version=14.4.0
Running in system-mode.                            
                                                    
Enter the GitLab instance URL (for example, https://gitlab.com/):
http://192.168.1.201/
Enter the registration token:
GR1348941UJvpbr3143Mdvzx2saZx
Enter a description for the runner:
[47394e7e62a6]: npm-report
Enter tags for the runner (comma-separated):
npm,npm-report            
Registering runner... succeeded                     runner=GR134894
Enter an executor: kubernetes, parallels, virtualbox, docker-ssh+machine, shell, ssh, docker+machine, custom, docker, docker-ssh:
shell
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

ポイントは… tags : npm,npm-reportとshellです。

あと、URLやtokenは個人の設定にしてやってください

登録されるとこんな感じで表示されます。
今回はGroupにしました

.gitlab-ci.yamlにレポート作成を定義します

次にgitlab-ciファイルにレポートの作成を定義します。

記述内容の抜粋はこのような感じに書きました

api-doc:
  tags:
    - npm-report
  stage: test
  before_script:
    - npm install
  script:
    - redoc-cli build ./documents/API.yaml -o ./documents/API.html
  cache:
    paths:
      - vendor/
      - node_modules/
  artifacts:
    paths:
      - documents/