現在業務でメンズファッション関連のサービス開発をしていて、RailsでバックエンドAPIを、SwiftUIでiOSアプリを作成しています。サービスで使われるREST APIの構築において、ドキュメントの作成にSwaggerを利用したので、まとめていきます。


Swaggerとはなにか

Swagger: API Documentation & Design Tools for Teams

Swaggerは、開発者がRESTful Webサービスを設計、構築、文書化、および利用するのに役立つツールの大規模なエコシステムに支えられたオープンソースのソフトウェアフレームワークです。(Wikipediaから引用)

Swaggerは公式で主に3つのオープンソースツールを提供しています。

NameDescription
Swagger CodegenOpenAPI仕様定義からサーバースタブとクライアントSDKを生成するツール
Swagger EditorOpenAPI仕様でAPIを設計するためのAPIエディタ
Swagger UIインタラクティブなUIでOpenAPI仕様の定義を可視化するツール

OpenAPI仕様の定義ファイル作成/編集

OpenApi Specification

OpenAPI仕様に関するドキュメントはこちらから参照できます。ファイルフォーマットはJSON, YAMLから選択できます。以前参画していたプロジェクトではYAMLファイルだったため使い慣れており、比較的シンプルに記述できるのでYAMLを選択しました。

このドキュメントを参照しながら愚直にドキュメントを作っていくのは正直大変です。今回は以下の記事を見て Stoplight Studio というサードパーティ製のGUIエディタの存在を知り、非常に便利そうだったので導入から利用することにしました。基本的にドキュメントの編集作業は公式のSwagger Editorを使わず、Stoplight Studioと普段から使い慣れているneovimで行いました。

本当に使ってよかったOpenAPI (Swagger) ツール

無料で利用でき、GUI操作でYAMLに変換していってくれます。またLintterも備えており、下部にリアルタイムでエラーを表示してくれるのもよかったです。

ちなみにneovimだと、coc.nvimプラグインはyamlファイルにも対応しており、エラー表示や補完機能があります。(だいたいのフォーマットに対応しているのでめちゃくちゃ便利です。)


APIドキュメントの確認

Swagger UI

ドキュメントの確認にはSwagger UIを利用しました。サーバーを起動することでブラウザ上でAPI定義を確認でき、実際にエンドポイントを叩いた際の挙動まで確認することができます。事前に認証が必要なエンドポイントはYAMLに定義することでブラウザ上で認証することもできます。

以下のURLでサンプルプロジェクトのデモが行えます。

Swagger UI Live demo

今回導入したプロジェクトではDockerを利用していたので、docker-compose.yml にSwagger UIのコンテナを定義しました。Dockerを利用する方法は公式リポジトリに記載があったので参考にしました。

InstallationConfiguration

ファイルの分割, コンポーネント化

このままドキュメントにAPIを追加していくと、小規模なプロジェクトであっても1000行程度はすぐに超えてしまい、ファイルサイズが大きくなって重くなるのもありますし、なにより今後の管理が大変になるでしょう。OpenAPI 3.0であれば $ref を使うことによって response body などをコンポーネント化して使いまわしたり、エンドポイントの定義を呼び出すことができたりします。

Using $ref
    '400':
      description: Bad Request
      headers: {}
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/400-bad_request.yaml'

こんな感じで同ファイルの定義を呼び出したり、

paths:
  /users:
    $ref: '../resources/users.yaml'
  /users/{userId}:
    $ref: '../resources/users-by-id.yaml'

他ファイルに定義を分けて呼び出すこともできます。

ここで一つ問題があり、公式ドキュメントに異なるファイルの定義を呼び出すことができると書いてあるにも関わらず、Swagger UI上ではエラーとなってしまい表示できませんでした。


他のUIツールの検討

ReDocredoc-cli

redoc-cli というツールを使えば、分割したファイルを読み込むことができそうだったので一度使ってみることにしました。

$ yarn global add redoc-cli
$ redoc-cli serve [openapi.yamlのパス] --watch

--watch option は変更を監視してくれるみたいです。

Swagger UIと比べて洗練されているデザインで、構造もシンプルなので良い印象を受けました。

ただ、

などのデメリットもありました。

試行錯誤していたところ、Swagger UIの問題を解決するPRがなんと2日前マージされていました!タイムリーすぎて感動。

Allow local ref's to be served by nginx #5565

Swagger UIは以前のプロジェクトで使い慣れていて、ファイルを分割できない以外は特に不満もなかったので、すぐに戻しました。PRを参考に docker-compose.yml を修正して起動したところ、無事ドキュメントが表示されました!🎉🎉


さいごに

初期の学習コストは少なくないですが、OpenAPIを使うことでREST APIのI/F定義をわかりやすい形で共有できるので、チーム開発の際には是非とも取り入れたいですね。関連するライブラリは紹介したもの以外にももちろんあるので、様々なツールを使い比べてみるといいでしょう。