2022年11月8日 2022年11月8日 By wataru In How to Gitlab, プログラム作成 GitLabgitlab-runnerswagger

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

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を作ります。
詳細は前回の記事にて参考ください

http://35.78.51.61/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/

はい、runnerの実行切り分けをtagsで行いましたのでnpm-report作る用のタグを指定しています。

あとは… 意味はありませんがnpmを使うのでnpm installを実行しました。

実際のレポート作成はscriptにて記述します

あとは… npm installしているのでキャッシュにディレクトリnode_modulesを指定しておきます。
composer は使わないのでvendorは注意がされます

重要なポイントですが、artifactsにてレポートをアーカイブ化します。

これでgitlab-ciの定義は終了です

レポートを取得する

はい、ここまでくるとCI実行時にtestフェーズでレポートが作成されます

レポートだったら本来はtestパス後に作りそうですが、APIドキュメントなので最初に作りました

作成後のレポートの取得はパイプラインの右にあるダウンロードボタンを押下するとバッチ単位のアーカイブファイルが取得できます

api-doc:archiveを押下するとzipファイルがダウンロードされます

アーカイブを展開するとdocumentsディレクトリの内容とhtmlファイルが取得できます
.gitignoreはダサいですねw

これでCI実行タイミングでAPIレポートが提供されるようになりました

え？Webサーバに上げないの？とお思いでしょうが…
mainブランチならWebサーバにあげることを考えますがサブブランチなら実行単位で出来る方がわかりやすいです
上げ方はscriptにscpとか書けば十分でしょう。
もっとスマートにするならGitlab-pageとか使うと良いですかね…

終いに

今回はAPI作成にswaggerを使いますよ！とswagger使っても可読性が低いからHTML化するgitlab-runner作ったぞ！とやってみました

swagger記述の仕方はまだまだ種状態（若葉にもなっていません）これから勉強します。

ついでにredoc使いましたが…. modelとか例とかがちゃんと表示されないので別のものを使っても良いですね
npmだったらコマンドを変えてやればOKです。

一番見やすいのはやっぱりswagger-editorですかね…

InteliJのOpenAPIも見やすいですが、動作が不安定ですw

むっちん、むっちん、ぷりんぷりんな日々