SwaggerをGitHub Pagesで公開する
こんにちは、@nerusanです。
みなさんは、swaggerを利用したことはありますでしょうか。
REST APIのインターフェース部分となり、
バックエンドとフロント分離した開発をするようになってからは、欠かせないのではないでしょうか。
ただ、定義したswaggerを公開する作業など、めんどくさかったりします。
そこで、今回は、swaggerをGitHub Pagesで簡単に公開する方法を紹介します。github pagesを利用するとマージの旅に、自動でデプロイしてくれるため、とても便利です。
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ディレクトリしか選べないためです。
$ mkdir docs
$ cd docs
$ touch 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のページにあるファイルを利用します。
上記のGitHubのビルド後のファイルが入っているdistディレクトリの配下を利用します。
まずは、zipファイルをダウンロードします。
そして、dist配下全てのファイルをswaggerディレクトリに配置します。
$ 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を編集します。
以下のドキュメントを参考にしました。
<!-- 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