今更Swagger Spec + ReDoc + Firebase HostingでAPI仕様ページを作ったら劇的に捗った件について

Last updated at 2024-05-02Posted at 2019-02-15

はじめに

REST APIを開発する際に、開発メンバとAPIの仕様に関して
恥ずかしながらこんな感じで共有していました。

さすがにダルすぎる....と思い今更ですが

Swagger Spec
ReDoc
Firebase Hosting

を使って、API仕様をWebブラウザで開発メンバに共有するようにしたので
そのやり方について書きます。

TL;DR

(当然だが)APIドキュメントを作ると捗るので、ちゃんと書こう
- HTMLをホスティングして公開すると、常に全員が同じ仕様を見ることができるので良い。
  - Excelとかで仕様書渡しちゃうと、いろんなバージョンが各人のPCに出回るので...
ReDocは導入が超簡単で、ページもおしゃれなのでオススメ
Firebase Hostingを使ってできるだけ労力をかけずに公開すると捗る
- 閲覧可能な接続元IPアドレス制限やベーシック認証などをかけましょう
swagger.yamlの更新が少しダルい

急いでいる方は直接手順をご覧ください。
手順

各ツールの簡単な紹介

Swagger Spec

Swagger Spec はRESTful APIを構築するためのオープンソースのフレームワーク「Swagger」の書式で記述した仕様書です。JSONもしくはYAML形式で記述します。

以下のようなAPI仕様を書くことで、以下のようなページの生成にも使えます。

詳しくは以下を参照
Swaggerの概要をまとめてみた。

ReDoc

API仕様を書いたswagger.yaml, swagger.jsonを読み込みHTMLページを生成する APIドキュメンテーションツールです。

Swagger UIでもHTMLは生成できますが

見た目がおしゃれ
多少のカスタマイズが可能

ということで、今回はReDocを採用しました。

HTML に redoc.min.js と swagger.yaml(or swagger.json) を読み込ませるだけ以下のようなページを生成できます。

今風なデザインでヌルヌルと動きます。

ReDoc GitHub ページ
https://github.com/Rebilly/ReDoc

参考
Swagger Specから静的なHTMLを作るHTMLジェネレータを色々ためしてみた
 ReDoc - Angular な静的 Webページを生成できる REST API ドキュメンテーションツール

Firebase Hosting

Firebase Hostingは、Google が提供しているモバイルおよび Web アプリケーションのバックエンドサービス「Firebase」の静的コンテンツホスティング機能です。無料で利用でき、デフォルトでHTTPS対応されています。

手順

1. Firebase Hosting用プロジェクトの作成

Firebase Hostingに公開するプロジェクトを作成します。
今回はこのプロジェクト内でAPIドキュメントページを作成します。

手順の詳細は以下が参考になります。
Firebase Hosting でWebサイトを公開する方法

2. Swagger Specを書く

開発しているREST APIの仕様をSwagger Specに書きます。
Swagger Editor
を使うのがおすすめです。

以下、サンプル。

swagger.yaml

swagger: '2.0'

info:
  version: "1.0.0"
  title: sample swagger spec

paths:
  /posts/{id}:
    get:
      description: |
        description
        説明文

      parameters:
        -
          name: id
          in: path
          description: Id of array
          required: true
          type: number
          format: double

      responses:
        200:
          description: Successful responses
          schema:
            title: ArrayOfPosts
            type: array
            items:
              title: Posts
              type: object
              properties:
                name:
                  type: string
                title:
                  type: string
                content:
                  type: string

3. ReDocでAPIドキュメントページを生成する

ReDocを使って、swagger.yaml(or swagger.json)を元にAPIドキュメントページを生成します。

3-1. ReDocのインストール(CDNを利用する場合は不要)

yarnを使ってインストール

yarn add redoc

npmを使ってインストール

npm install redoc --save

3-2. redoc モジュールをHTMLから読み込む

Firebase Hostingに公開するAPIドキュメントページ(index.html)に以下を追加します。

CDN経由で読み込む場合

<script src="https://cdn.jsdelivr.net/npm/redoc/bundles/redoc.standalone.js"> </script>

3-1.でインストールしたnode_modulesを読み込む場合

<script src="./node_modules/redoc/bundles/redoc.standalone.js"> </script>

index.htmlの全体像は以下になります。

index.html

<!DOCTYPE html>
<html>
  <head>
    <title>ReDoc - sample API</title>
    <link rel="icon" href="./favicon.ico">
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>
    <redoc spec-url="./spec/swagger.yaml"></redoc>
    <script src="./node_modules/redoc/bundles/redoc.standalone.js"></script>
  </body>
</html>