はじめに

今回は前回作成した、OpenAPIをSwagger-uiというツールを使用しGitHubPagesに公開していきたいと思います。
前回の記事はこちら

Swagger UIとは

公式より引用

Swagger UI allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without having any of the implementation logic in place. It’s automatically generated from your OpenAPI (formerly known as Swagger) Specification, with the visual documentation making it easy for back end implementation and client side consumption.

簡単に言うと、定義したOpenAPIの仕様から視覚的なドキュメントを自動生成してくれるツールになります。

自分が作成したopenapiのファイルを読み込ませるだけで以下のように良い感じに静的ファイルを生成してくれます。

定義した仕様から生成するので変更があった際も手動で更新する必要がなく、常に全員が最新のドキュメントを参照できるというメリットがあるようです。

以下のようなステップで行います。

OpenAPIの作成
index.htmlにswagger-uiを読み込み、定義したopenapiを読み込みドキュメントを生成
GitHubPagesの設定

OpenAPIの作成

具体的な書き方等については前回の記事を参照してもらえればと思います。

OpenAPIのファイルはルートディレクトリにdocsというディレクトリを作成しその配下に配置します。
githubpagesの参照が指定したブランチのルートかdocsしか指定できないためこのようにしています。

index.htmlにswagger-uiを読み込み、定義したopenapiを読み込みドキュメントを生成

公式を見ると様々なswaagger-uiの使用方法が記載されています。

今回は一番手軽そうなunpkgを用いた方法で行っていきます。

unpkgとは？

HTMLなどに直接npmパッケージ、ライブラリを読み込むものになります。

swaggerのunkpgでの利用方法は以下の通りです

公式より引用

index.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <meta name="description" content="SwaggerUI" />
  <title>SwaggerUI</title>
  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui-bundle.js" crossorigin></script>
<script>
  window.onload = () => {
    window.ui = SwaggerUIBundle({
      url: 'https://petstore3.swagger.io/api/v3/openapi.json',
      dom_id: '#swagger-ui',
    });
  };
</script>
</body>
</html>

index.html

<script src="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui-bundle.js" crossorigin></script>

こちらの箇所でswagger-uiを読み込んでいます。
これだけでswagger-uiが提供するコードを使用することができるようになります。

ドキュメント生成部分

index.html

<script>
  window.onload = () => {
    window.ui = SwaggerUIBundle({
      url: 'https://petstore3.swagger.io/api/v3/openapi.json',
      dom_id: '#swagger-ui',
    });
  };
</script>

ドキュメントのUIの生成はSwaggerUIBundle関数が行います。
こちらの関数に２つのオプションを渡しています。
url には　読み込ませるopenapiのファイルのパスを渡します。
dom_idにはSwagger UIを描画するHTML要素のIDを渡します。

それを
window.onload
つまり、ページが読み込まれたタイミングに発火させて表示するような処理になっています。

idの指定はこのままで良いのでURLだけ自身が定義しているopenapiのパスに指定してあげる必要があります。

index.htmlファイルをdocs配下に作成し、以下のようにパスだけ変更して記述

index.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <meta name="description" content="SwaggerUI" />
  <title>SwaggerUI</title>
  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui-bundle.js" crossorigin></script>
<script>
  window.onload = () => {
    window.ui = SwaggerUIBundle({
      url: './openapi.yml', // urlをopenapi.ymlのあるパスに指定
      dom_id: '#swagger-ui',
    });
  };
</script>
</body>
</html>

これだけでswagger-uiの設定は終わりです。

github-pagesの設定

最後にgithub-pagesを行います。
リポジトリのページからsetting　⇨ サイドバーのPages の順番で遷移
Build and deploymentを以下のように設定

これでmainブランチのdocs配下をデプロイするようになります。

あとは、pushしてmainブランチにマージ

デプロイが成功していれば
リポジトリのDeploumentsが以下のようになっています

クリックしてページ遷移すると

公開に成功です！

まとめ

今回は手軽にunpkgを使って行いましたが、github actionsでswagger-cliなど併用することで、openapiの定義が正常かどうか検証を行った上で自動デプロイするなどより安全に行う方法もあるようなので、また余力あれば挑戦してみたいと思います。次回はこのopenapiを使用したテストやコード自動生成をやってみたいと思います。

swagger-uiでOpenAPIをGitHub Pagesに公開する

はじめに

Swagger UIとは

OpenAPIの作成

index.htmlにswagger-uiを読み込み、定義したopenapiを読み込みドキュメントを生成

unpkgとは？

github-pagesの設定

まとめ