はじめに

こんにちは🌞 システム開発推進部システム開発第3グループの小河です。 普段はレコチョクの各サービスが共通で利用するバックエンドシステムの開発や運用を担当しています。

本記事では、 Swagger EditorとRedocとGitHub Pagesを組み合わせ、OpenAPIベースの仕様書を管理・社内公開する方法について、事例を通してご紹介します。

APIドキュメントツールを用いる背景

弊社では様々なサービスを展開していますが、共通で必要となる機能も多くあります。 (例: 課金・音源の配信など) そのため、それぞれの共通機能を主にREST APIとして提供し、他組織が開発するサービスがそのAPIを利用して機能を実現しています。 我々システム開発第3グループにてそれらAPIの開発を行っている都合上、 API仕様書の管理と社内の他組織への公開を行う必要があります。

Postmanを利用する上での課題

我々システム開発第3グループでは、APIドキュメントツールとしてPostmanを利用していました。 しかし、ユーザーごとに課金がなされる料金体系(2025/03現在)のため、コスト上の課題がありました。 社内の運用方法として 利用ユーザー数に上限を設けたため、新たに案件に参画したメンバーはPostmanをすぐに利用を開始できない状態が発生していました。

なぜSwagger Editor + Redoc + GitHub Pagesか

そこで、Swagger Editor + Redoc + GitHub Pagesを用いてAPI仕様書を管理・社内公開することにしました。

それぞれのツールは以下のように利用します。

• Swagger Editor Swagger EditorはOpenAPIに則ってAPI仕様を記述可能なエディタです。 こちらを利用してAPI仕様を記述します。
• Redoc RedocはOpenAPI準拠で記述されたAPI仕様からドキュメントを生成するツールです。 Swagger Editorで記述したAPI仕様をHTMLとして出力します。
• GitHub Pages GitHub PagesはGitHubリポジトリに配置した静的コンテンツをホスティングするサービスです。 Redocで生成したHTMLファイルをGitHubリポジトリ上に配置し、社内に公開します。 (他組織からxxシステムのAPI仕様書が欲しい！と言われればこのURLを渡すだけです)

この方法には以下の利点があります。

• コストが低い Swagger EditorおよびRedocはオープンソースということもあり、商用利用であっても無償で利用可能です。 GitHub Pagesについても、弊社については元々GitHubを用いているため、追加のコストを要することはありませんでした。
• OpenAPIという標準的なフォーマットを利用できる PostmanはPostman CollectionというPostman独自のフォーマットを用いています。 一方でOpenAPIは広く知られたフォーマットのため、API仕様を記述するツールも豊富に存在します。例えばStoplight Platformを用いれば、PostmanのようにGUIによるサポートを受けつつAPI仕様を記述できます。 さらに、生成AIによるサポートも受けやすいです。
• GitHub上に配置することによるシナジーを受けられる API仕様書をGitHubリポジトリ上に配置することになるため、以下の恩恵を受けられます。 ①GitHubの仕組みを利用できるため、レビューを行いやすい ②GitHub Actionsを利用してCI/CDを構築することで、仕様書の生成、ホスティングまでを自動化できる ③ドキュメント類をGitHubに集約できる

API仕様書を公開するまでの手順(一例)

具体的なイメージをつけていただくため、API仕様書を公開するまでの具体的な手順を紹介します。

1. Swagger EditorでAPI仕様を記述

Swagger Editorをダウンロードし、 API仕様を記述していきます。 もしくはVisual Studio Code拡張であるOpenAPI (Swagger) Editorを利用して記述することもできます。 GitHub Copilotなどの生成AIのサポートを受けやすいためおすすめです。

(ちなみに画像に写しているAPI仕様は「OpenAPI 3.0.0に則ってサンプル的なAPI仕様を書いて」という指示でGitHub Copilotによって生成したものです)

そのようにして記述したAPI仕様をyamlファイルとして保存します。

2. RedocでHTML化

こちらに従いRedocly CLIをインストールの後、下記コマンドを実行します。

$ redocly build-docs {1.で保存したyamlファイル} --output=index.html

そうすると、 index.htmlとして下記のようなHTMLファイルが生成されます。 これがAPI仕様書となります。

3. GitHub Pagesに配置

生成された index.html(API仕様書)をGitHubリポジトリに配置し、GitHub Pagesで公開します。 (詳しい方法はこちらなどを参照してください)

さらにGitHub Actionsを用いることで「2. RedocでHTML化」を自動化することも可能です。

新方式へ切り替えた効果

我々システム開発第3グループのAPI仕様書のうちPostmanで管理・公開されていたものは、今回ご紹介した方法に全て切り替えることはできていないものの、着々と進んでいる状況です。 新規に作成するAPI仕様書も新しい方法で作成されています。

その結果、冒頭で記載したようなコストや利用ユーザー数の上限についての課題を解決することができました。

Swagger Editor + Redoc + GitHub Pagesを運用してみて分かったデメリット

• 新規作成のハードルの高さ PostmanではAPI仕様を記述するためのGUIが用意されているため、それを用いてAPI仕様を記述することができます。 一方で、Swagger EditorではOpenAPIのフォーマットに則ってAPI仕様を記述する必要があり、そのハードルは高いです。 しかし、以下のような解決方法によってある程度ハードルを下げることができています。 ①Stoplight Platformなど、GUIツールを用いる ②生成AIのサポートを積極的に受ける ③(Postmanから移行する際に限りますが)OpenAPIのフォーマットへ変換するようなツールを用いる
• 場合によってはGitHub Pagesによる社外への公開ができない 本記事ではあくまで 社内公開にフォーカスしておりスコープから少し外れてしまいますが、このような欠点があります。 例えば採用しているGitHubの認証方式の関係上、GitHub Pagesにホストされたページに誰もがアクセスできないような状況も存在します。 そのような場合は、Amazon S3で静的ホスティングするといった方法でWebに公開するという手段を取るのが良さそうです。
• Postmanが提供する機能のうち、API仕様書の管理と公開しか代替することができない 当然と言えば当然なのですが、Postmanが提供するAPIテストといったような機能を実現することはできません。 (ただ、そのような用途ではPostmanを用いてはいなかったので、これはあまり問題となりませんでした)

とはいえ、いずれも代替手段が存在するため、利用する上でこれといったネガティブが生じることはありませんでした。

おわりに

本記事では、Swagger Editor + Redoc + GitHub Pagesを用いてAPI仕様書を管理・社内公開する方法について解説しました。 API仕様書を管理・公開する方法には様々なものがありますが、その中でも本記事で解説した方法も一つの選択肢としてご検討いただければと思います。