OpenAPI Specification (またはSwagger) を、
無料で手軽にWeb公開する方法をご紹介します。
この記事では、OpenAPIそのもの、OpenAPI Specificationについては言及しません。
🚨注意🚨
この記事で紹介する方法はパブリックな共有方法になります。
アクセス制限等が必要な場合は別途考慮する必要があります。
概要
- OpenAPI Specification (またはSwagger) のyamlファイル
- ReDocを採用したhtmlファイル
これらをgithubにpushし、GitHub Pagesでホスティングします。
手順
yamlファイルを作成する
なにはともあれ、API仕様を定義したyamlファイルが必要です。
-
Swagger Editor
手軽なものですと、Swaggerが公式で提供しているSwagger Editorがあります。
ブラウザでyamlファイルを編集することができます。
editor.swagger.io -
Swagger Viewer
VSCodeのプラグインでyamlをプレビューできるものがあります。
Swagger Viewer
Htmlファイルを作成する
yamlファイルを静的なhtmlに変換するツールはいくつかあります。
OpenAPI公式が公開している openapi-generator も機能を提供しています。
今回は手軽に利用できる ReDoc を使います。
⭐️ReDocの特徴は yamlからhtmlへの変換作業が不要 なことです
htmlファイルのテンプレートはgithubに公開されています。
テンプレートの<redoc>タグはyamlファイルへのパスを指定します。
例として、以下のような構成のgitリポジトリを作成します。
(後ほどGitHub Pagesでホスティングするため、gitリポジトリをベースに考えます)
/{repo_root}
├─ index.html
└─ wabapi.yml
この場合、htmlファイルは以下のようになります。
<!DOCTYPE html>
<html>
<head>
<title>ReDoc</title>
<!-- needed for adaptive design -->
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
<!--
ReDoc doesn't change outer page styles
-->
<style>
body {
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<!-- 👇yamlファイルへのパス -->
<redoc spec-url='./webapi.yaml'></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
</body>
</html>
GitHubにリポジトリを用意する
GitHub Pagesで公開するには、関連するリポジトリが必要です。
GitHub Pagesで公開できる単位は3つです。
- プロジェクト
- ユーザー
- Organization
当然、ユーザー単位で公開できるGitHub Pagesは1ユーザーあたり1つまでとなります。
ユーザーまたはOrganizationで公開
リポジトリ名を <user>.github.io または <organization>.github.ioとした場合、
master ブランチの内容が、以下のURLで公開されます。
http(s)://<user>.github.io/
http(s)://<organization>.github.io/
これらは特に設定は不要です。自動的に公開されます。
プロジェクトで公開
リポジトリ名は自由です。
ブランチはmasterまたはgh-pagesのいずれかを選択できます。
デフォルトで以下のようなドメインで公開されます。
http(s)://<user>.github.io/<repository>
http(s)://<organization>.github.io/<repository>
これらは公開ソースのブランチの設定が必要です。
GitHub Pages 早見表
| ユーザーまたはOrganizationで公開 | プロジェクトで公開 | |
|---|---|---|
| GitHubのリポジトリ名 |
<user>.github.io または <organization>.github.io
|
自由 |
| 公開ソースのブランチ | master |
master または masterの/docs配下 または gh-pages
|
| 公開URL |
http(s)://<user>.github.io/ または http(s)://<organization>.github.io/
|
http(s)://< user >.github.io/<repository> |
GitHubにPushする
- 作成したyamlファイル
- 前項で示したhtmlファイル
この2点を以下のような構成でGitHubにPushします。
/{repo_root}
├─ index.html
└─ wabapi.yml
公開ソースのブランチにPushまたはMergeしましょう。
ブラウザで確認する
この早見表を参考にブラウザで公開されているかどうか確認します。
GitHubにPushしてから 最大で20分ほど かかることがあるようです。
まとめ
- ReDocは yamlからhtmlへの変換が不要で手軽です
- github pagesは静的ページをホスティングできます
- github pagesのリポジトリ名、公開ソースブランチ制約は早見表を参考に
(採用例) 北海道コロナ情報まとめサイト
OSSで開発されている北海道のコロナ情報まとめサイトは、
北海道のコロナ感染情報をWebAPIで公開しています。
このAPI仕様はこの記事の技術で公開されています。
https://codeforsapporo.github.io/covid19hokkaido_webapi/