TECHSCORE BLOG

クラウドCRMを提供するシナジーマーケティングのエンジニアブログです。

OpenAPI Specification から生成した API 仕様書を GitHub Pages で公開しました

Synergy! のバックエンドを担当している丸本です。

2020年5月に Synergy! API の後継機能となる Synergy! データベース API(以下、データベース API)をリリースし、それに合わせて API 仕様書も公開しました!

今回はテクニカルライティングのテの字も知らなかった私がはじめて API 仕様書を作成し、GitHub Pages で公開した道のりについてご紹介します。

f:id:techscore:20200622144437p:plain:w80 丸本 竜輔(マルモト リュウスケ)
2019年7月入社のバックエンドエンジニア。
広島県出身 / ビールが大好き

3度の飯よりビールが好きです!むしろ原材料麦なので主食です。
最近このご時世なので大好きな生ビールが飲めていません…私が世界で一番美味しいと思っている広島の某酒店さんで自粛明け最初の生ビールを飲みたいと思っています!
この記事に書いてあること
  • OpenAPI Specification から API 仕様書を作成する方法
  • GitHub の Organization アカウントについて
  • Organization アカウント全体に独自ドメインを適用する方法
この記事に書いていないこと
  • データベースAPI の詳細
  • OpenAPI の解説
  • Organization アカウントの運用について

目次

データベースAPIについて

データベースAPI は外部のシステムから、Synergy! のデータベース(マスター・履歴)の読み出し、登録・更新・削除などを簡単に行うことができる API です。

同様の機能を提供する Synergy!API という API がありますが、2009年にリリースされたAPIであり、プロトコルがSOAPであるため、今では使いづらいものとなっています。

また、Synergy!API は顧客マスタに紐づいて設定できる API 定義が1つだけだったり、項目の新規追加ができなかったりと不便な点がいくつもありました。

そこで Synergy!API をモダナイズし、かつより使いやすい API にすることを目指して、 OpenAPI を導入して RESTful なデータベースAPI を開発しました。

データベースAPI仕様書の開発

通常 API 仕様書の作成には以下の工程が必要になるかと思います。

  1. 仕様書の中身を書く
  2. 仕様書の見やすくわかりやすいデザインを考え、静的ページを作成する

特に 2. はかなり苦労する工程だと思います。見やすいデザインとは…わかりやすいデザインって…しかも HTML を自作しなくちゃいけない…等々。

しかし OpenAPI はドキュメンテーションツールが充実しており、この工程がかなり軽減されます! そのため仕様書の中身を充実させることに注力できます。

以下ではドキュメンテーションツールの選定について、また仕様書の開発の中で獲得したノウハウについてご紹介したいと思います。

API ドキュメンテーションツールの選定

開発チームでは Swagger 公式のドキュメンテーションツールである Swagger UI を、ドキュメント上から API を実行するためのサポートツールとして使用していました。しかし、Swagger UI が生成する HTML は各オブジェクト定義が最下部にあるため見づらく、仕様を把握するための API 仕様書としては正直言って不向きでした。

そこで API 仕様書の生成には ReDoc を採用しました。

ReDoc はデフォルトでとてもおしゃれな仕様書が出力されます。

f:id:techscore:20200605173226p:plain
また、ReDoc は章立てや構成など、出力される HTML ファイルを自由にカスタマイズをすることができます。

ReDoc でのドキュメント整備

以下では ReDoc を利用してドキュメントを生成する際につまずいた点、工夫した点を紹介します。

Authentication の表示場所指定

ReDoc はデフォルトでは securitySchemes で定義した内容を Authentication として表示します。

データベース API の実行には認証サーバにリクエストを送り、アクセストークンを取得する必要があります。その説明のため [はじめに/認証] という項目を設けましたが、関連情報である Authentication が別項目となってしまいます。

なんとかして Authientication を [はじめに/認証] の中に入れることはできないかと調べてみた結果、<SecurityDefinitions /> というタグを [はじめに/認証] の説明部に挿入することで解決しました!

 ### Synergy!データベースAPI リクエスト
 リクエストの際、Authorization ヘッダーにアクセストークンをセットしてください。
 #### listApiDefinition リクエストサンプル
 ```
 curl -X GET \
   -H "accept: application/json" \
   -H "Authorization: Bearer ${ACCESS_TOKEN}" \
   https://db.paas.crmstyle.com/apis/apidefinition.database/v1/accounts/...
 ```
 <SecurityDefinitions /> # ★これを追加

 ## ご利用までの流れ

f:id:techscore:20200622114019j:plain

Appendix の追加

説明に表を使いたいけど大きすぎて見づらくなってしまう、横道に逸れてしまう補足的な説明を追加したいなど、リンクで参照させることで、本文に書くのを避けたい箇所がいくつかありました。

最初は別にページを作成してリンク参照させようかと考えていたのですが、せっかくReDoc で綺麗なページができているので同じページでどうにかできないかと考え、ページの最後に Appendix を追加しました。

tags: の最後に追加することでページ最下部に追加されます。

tags:
  - name: ApiDefinition
    description: |
      サーバ間連携用の独自の REST API を作成することができます。
  - name: OpenApi
    description: |
      ApiDefinition で作成した API 定義を OpenAPI Document 形式で参照することができます。
  - name: DatabaseDefinition
    description: |
      Synergy! 内に登録されているデータベース設定情報を参照することができます。
  - name: Record
    description: |
      ApiDefinition で作成した REST API を実行することができます。
  - name: Appendix # ★ これを追加
    description: |

GitHub Pages で公開する

ReDoc で生成した HTML ファイルを GitHub Pages の機能を使って、Web上に一般公開します。

GitHub Pages のデフォルトではドメインが github.io になりますが、今回は独自ドメインを設定し、さらに https でアクセスできるように設定しました。

また、複数の仕様書をそれぞれ別リポジトリで管理し、GitHub Pages で公開できるように、リポジトリ単体ではなくアカウント全体に独自ドメインを適用しました。

アカウントについて

GitHub Pages での公開にあたり、Synergy! 専用の Organization アカウントを作成しました。 その際 Enterprise 版の機能は不要だったため、 Free アカウントを取得しました。

また今回は企業として仕様書を公開するため、個人向けの利用規約から企業向けの利用規約にアップグレードしました。

企業利用規約へのアップデートを行うには、まず GitHub Support にリクエストを送る必要があります。日本語のサポートもありますが、Enterprise 限定だったため今回は下記のようなリクエストを送りました。

Subject: About Upgrading to the Corporate Terms of Service

Dear Github Support Team.

We would like to upgrade to the Corporate Terms of Service.
Could you enable a banner on our organization's dashboard?
We will check and accept it.

Best regards
Ryusuke Marumoto

リクエストを送って翌日には返事があり、ダッシュボード上に規約アップグレード用のバナーが有効になっていました!

あとはそのバナーから規約に同意することで規約をアップグレードすることができます。

ドメインの取得

独自ドメインを設定するにはまずドメインを取得する必要があります。

ここでは独自ドメインとして docs.synergy-marketing.co.jp を利用します。 DNS に独自ドメインが GitHub Pages を指すように CNAME として synergy-dev.github.io を設定します。

リポジトリの構成

HTML ファイルを登録するリポジトリとは別に、アカウント全体に独自ドメインを登録するために ${アカウント名}.github.io という名前のリポジトリが必要になります。

最終的にリポジトリ構成は以下のようになります。

synergy-dev (Organization アカウント)
  + dbapi-reference
  + synergy-dev.github.io

dbapi-reference リポジトリには公開する仕様書の HTML ファイルを登録し、いくつかの設定をします。

synergy-dev.github.io リポジトリにはアカウント全体に独自ドメインを適用するための設定ファイルを登録します。

独自ドメイン適用

synergy-dev.github.io リポジトリに設定したい独自ドメインが記載された CNAME ファイルを作成します。

f:id:techscore:20200605173232p:plain
これだけで Organization アカウント全体の GitHub Pages に独自ドメインが適用されます!

公開対象ブランチ設定 / HTTPS 化

GitHub に仕様書公開用のリポジトリを作成し、作成した API 仕様書の HTML ファイルを push したら、いよいよ Pages での公開です。

Settings -> Options -> GitHub Pages -> Source をクリックし、master branch を選択しましょう。

たったこれだけで push した API 仕様書が GitHub Pages として公開されます!

また、独自ドメインを有効にするとデフォルトで TLS がオフになっています。 TLS をオンにしたい場合、Enforce HTTPS のチェックを入れることで HTTPS 化されます!

f:id:techscore:20200622114522p:plain


リポジトリ単位で独自ドメインを設定する場合
今回はデータベースAPI 仕様書以外にも公開対象の仕様書があり、それぞれを別のリポジトリで管理したかっため、仕様書公開用のリポジトリ(synergy-dev.github.io)を作成し、Organization 全体に独自ドメインを適用しました。
ひとつのリポジトリだけを独自ドメインで公開するならば、Settings -> Custom Domain を設定するだけで、そのドメイン名で GitHub Pages にアクセスできるようになります。
f:id:techscore:20200605173221p:plain

さいごに

OpenAPI Specification から生成した API 仕様書を GitHub Organization アカウントを作成して Pages で公開した道のりをご紹介しました。

現在データベース API 仕様書だけでなく、Syenrgy!API の仕様書および Syenrgy!メールAPI の仕様書も GitHub Pagesにて公開しています。

OpenAPI Specification + ReDoc + GitHub Pages でとてもお手軽に API 仕様書を公開することができます!

API 仕様書を公開してみたいけどめんどくさそう…という方はぜひ参考にしてみてください!