OpenAPI (Swagger) API仕様を無料で手軽にWeb公開する

7827 ワード
OpenAPI swagger ReDoc github-pages OpenAPI-Specification github-pages テキストリンク

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つです。
1. プロジェクト
2. ユーザー
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/