💭

SwaggerをGitHub Pagesで公開する

2022/10/29に公開約7,200字

こんにちは、@nerusanです。
みなさんは、swaggerを利用したことはありますでしょうか。

https://swagger.io/specification/

REST APIのインターフェース部分となり、
バックエンドとフロント分離した開発をするようになってからは、欠かせないのではないでしょうか。

ただ、定義したswaggerを公開する作業など、めんどくさかったりします。

そこで、今回は、swaggerをGitHub Pagesで簡単に公開する方法を紹介します。github pagesを利用するとマージの旅に、自動でデプロイしてくれるため、とても便利です。

https://docs.github.com/ja/pages/getting-started-with-github-pages/creating-a-github-pages-site

1. GitHubプロジェクトを用意

まず、swaggerを公開するためのGitHubプロジェクトを作成します。
通常は、バックエンドプロジェクトに含めるかなって思います。
GitHub上で、例としてsample-backendを作成し、それを自身の環境にcloneします。

$ cd dev  # 自身の開発環境に移動
$ git clone https://github.com/Yuki-TU/sample-backend.git
$ cd ./sample-backend

2. openapi.ymlの用意

次にopenapi.ymlを用意します。こちらは、swaggerの定義ファイルとなります。ここで定義されたファイルをもとに、swaggerページが作成されます。

どういったAPIなので、どういったエンドポイントがあるのか、どういったリクエストでレスポンスが帰ってくるのかを定義しましょう。

作成する場所、docsディレクト配下に作る必要があります。これは、GitHub Pageを公開するディレクトリは、ルートディレクトまたは、docsディレクトリしか選べないためです。

shell
$ mkdir docs
$ cd docs
$ touch openapi.yml

具体的な記述方法は公式ページを参考に作っていきましょう。

https://swagger.io/docs/specification/about/

openapi.yml
openapi: 3.0.0
info:
  version: 0.0.0
  title: RESTful API
  description: >-
    バックエンドAPI
servers:
  - url: 'http://{host}:8081/api/v1'
    description: go service api server endpoint application
    variables:
      host:
        default: localhost
        enum:
          - localhost
paths:
  /register:
    post:
      tags:
        - user
      summary: ユーザ登録
      description: |
        クライアントが入力する情報をもとにユーザ情報を登録する
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: 山田太郎
                email:
                  type: string
                  format: email
                  example: yamada@hoge.hoge
                password:
                  type: string
                  format: password
                  example: qwerty123456789
              required:
                - name
                - email
                - password
      responses:
        '200':
          description: ユーザ情報登録成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    format: number
                    example: 200
                  method:
                    type: string
                    example: "POST"
                  message:
                    type: string
                    example: "ユーザ登録に成功しました。"
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 1
                required:
                  - statusCode
                  - method
                  - message
                  - data
        '409':
          description: |
            登録済みのメールアドレス
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    format: number
                    example: 409
                  method:
                    type: string
                    example: "POST"
                  message:
                    type: string
                    example: "登録済みのメールアドレスです。"
                  data: 
                    type: object
                    example: null
        '500':
          $ref: '#/components/responses/500Error'
components:
  responses:
    500Error:
      description: |
        サーバー上のエラー
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
                format: int64
                example: "500"
              method:
                type: string
                example: "POST"
              message: 
                type: string
                example: "サーバー側で何らかのエラーが発生しました。"
              data:
                type: object
                example: null

3. swaggerページの準備

openapi.ymlだけでは、ページを公開することはできません。そこで定義した値を表示するhtml, css, JavaScriptを用意する必要があります。それは、swagger-uiのGitHubのページにあるファイルを利用します。

https://github.com/swagger-api/swagger-ui

上記のGitHubのビルド後のファイルが入っているdistディレクトリの配下を利用します。

https://github.com/swagger-api/swagger-ui/tree/master/dist

まずは、zipファイルをダウンロードします。

そして、dist配下全てのファイルをswaggerディレクトリに配置します。

shell
$ ls
openapi.yml
$ mkdir swagger
$ cd swagger
$ mv ~/Downloads/swagger-ui-master/dist/* ./
$ ls
favicon-16x16.png                       oauth2-redirect.html                    swagger-ui-es-bundle-core.js            swagger-ui-standalone-preset.js         swagger-ui.js
favicon-32x32.png                       swagger-initializer.js                  swagger-ui-es-bundle-core.js.map        swagger-ui-standalone-preset.js.map     swagger-ui.js.map
index.css                               swagger-ui-bundle.js                    swagger-ui-es-bundle.js                 swagger-ui.css
index.html                              swagger-ui-bundle.js.map                swagger-ui-es-bundle.js.map             swagger-ui.css.map

4. ファイルの修正

次にopenapi.ymlを読み込むように、index.htmlを編集します。

以下のドキュメントを参考にしました。
https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/installation.md#unpkg

docs/swagger/index.html
<!-- HTML for static distribution bundle build -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>Swagger UI</title>
    <link rel="stylesheet" type="text/css" href="./swagger-ui.css" />
    <link rel="stylesheet" type="text/css" href="index.css" />
    <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
    <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
  </head>
  <body>
    <div id="swagger-ui"></div>
    <script src="./swagger-ui-bundle.js" charset="UTF-8"> </script>
    <script src="./swagger-ui-standalone-preset.js" charset="UTF-8"> </script>
    <script src="./swagger-initializer.js" charset="UTF-8"> </script>
+   <script>
+     window.onload = () => {
+       window.ui = SwaggerUIBundle({
+         url: '../openapi.yml',
+         dom_id: '#swagger-ui',
+         presets: [
+           SwaggerUIBundle.presets.apis,
+           SwaggerUIStandalonePreset
+         ],
+         layout: "StandaloneLayout",
+       });
+     };
+   </script>
  </body>
</html>

5. GitHubPagesの設定

1.で作成したGitHubプロジェクトを開きます。
Settings→Pagesに移動します。
ソースはdeploy from a branch、 ブランチはmain, フォルダはdocsを選び保存を押します。

数分経つと同ページの上記にURLが表示されます。表示されてから以下のURLにアクセスするとと、今回作成したswaggerのページが表示されます。
https://{自身のGitHubアカウントid}.github.io/sample-backend/swagger

後は、修正するたびに、mainブランチにマージすると、自動で更新されます。

まとめ

以上、swaggerをGitHub Pagesに公開する方法を紹介しました。
簡単にできるので、ぜひ試してみてください。

また、間違っていることなどあれば、コメントいただければと思います。

Discussion

ログインするとコメントできます