Swaggerをオシャレに公開したい！ on GitLab Pages

Last updated at 2024-01-27Posted at 2023-12-14

はじめに

この記事は富士通クラウドテクノロジーズ Advent Calendar 2023 の 15 日目の記事です。

昨日は @tomonai さんの Google ColaboratoryでChat GPTをやってみた話でした。
OpenAIを使ったプログラミングを気軽に試してみたい場合にとても参考になりますね

Swagger(OpenAPI)形式で記述した仕様書をもとに、APIドキュメントをWEB公開する方法の1つを紹介します。
記事の最後にコピペだけで実行可能な状態の.gitlab-ci.ymlも記載します。

成果物

サイト

キャプチャ

モチベーション

社内GitLabの大型マイグレーションをした話でも紹介されてるようなGitLabにおいて、Pages機能を自チームで何か活用できてないかなと思っていました。

jamstack.org で静的サイトジェネレーターのトレンドをあさっていたところ、SlateというAPIに特化したツールがあるようです。ただし利用するにはSlate形式のマークダウンが必要でした。

手元にはSwagger、そして widdershins というSwaggerをSlate互換形式に変換するツールも見つけました。

そして出来上がったものがこの記事になります。

ビルドとデプロイ

必要なもの

Swagger または OpenAPI形式で記述したAPI仕様書
GitLabのアカウント（gitlab.comの無料アカウントでも可）
- 以下説明のため各種コマンドを記述していますが、それらの実行は最後に紹介するGitLab のパイプライン上で完結できます

静的サイトのビルド

今回はサンプルとして作ったBooksAPIのSwaggerをもとにサイトを作ってみます。

books-swagger.yaml

swagger: "2.0"
info:
  version: 1.0.0
  title: Books API
  description: 本の登録を行うAPIです
host: books.example.com
basePath: /v1
schemes:
  - http
consumes:
  - application/json
produces:
  - application/json
paths:
  /books:
    get:
... 省略

1. Swagger(OpenAPI)をSlate形式に変換

まずはSwagger形式のYAMLをマークダウンに変換します。Node.js製のwiddershins というツールを使います。

OpenAPI / Swagger / AsyncAPI / Semoasa definition to Slate / ReSlate compatible markdown

とあるように、ドキュメント生成ツールであるSlateと、互換のある形式にSwaggerを変換できます。

コマンドのオプションは色々とありますが、以下のように入力と出力だけ指定できれば生成できます。

npm install widdershins
npx widdershins books-swagger.yaml -o generated.slate.md

2. 静的サイトとして生成

サイト生成には Slate を利用します。
StripeやPayPalのAPIドキュメントからインスパイアを受けたとの記述もあり、洗練されたデザインとコードサンプル付きなドキュメントが生成できそうです。

公式ドキュメント Using-Slate-Natively が参考になりますが、概要としてはSlateのリポジトリをcloneして、source/配下にあるコンテンツをもとに生成するという仕組みです。

Slateのclone

まずは先ほど生成したマークダウンをsource/配下に配置します。Slateはシングルページのため、index.html.mdだけ上書きすれば配置は完了です。

git clone https://github.com/slatedocs/slate.git
mv generated.slate.md slate/source/index.html.md

ビルド

マークダウンの配置までできたら、最後に静的サイトとして生成すれば完成です。

方法はいくつかありますが、middleman(Ruby製)でビルドする方法が簡単でした。

以下のようにbundle execすることでbuild/配下に生成できます。

※ Using-Slate-Nativelyに書いてあるように、OSによっては追加でインストールが必要な依存がある場合もあります。

cd slate
bundle install
bundle exec middleman build

GitLab Pagesに公開

せっかく生成できたので、WEB上に公開したいです。ホスティングする方法はいくつかありますが、今回ははじめに触れたようにGitLab Pagesで公開してみます。

とは言っても簡単でこの記事に今まで張られているコマンドをCI上で実行すれば終わりです。

具体的にはリポジトリの .gitlab-ci.yml に以下のようなジョブを追加します。(リポジトリがない場合はプロジェクトを新規作成し、.gitlab-ci.yml とSwagger形式のYAMLをコミットします)

.gitlab-ci.yml

pages:
  image: cimg/ruby:3.2-node
  stage: deploy
  variables:
    SWAGGER_PATH: "books-swagger.yaml"
  script:
    # Slate形式に変換
    - npm install widdershins
    - npx widdershins $SWAGGER_PATH  -o generated.slate.md
    # 静的サイトとして生成
    - git clone https://github.com/slatedocs/slate.git
    - mv generated.slate.md slate/source/index.html.md
    - cd slate
    - bundle install
    - bundle exec middleman build
    - mv build ../public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH