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

Swaggerとはなにか

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

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

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

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

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

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

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

APIドキュメントの確認

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

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

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

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

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

    '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ツールの検討

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

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

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

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

ただ、

• Docker上で起動するとなぜか左側の目次が機能しない
• エンドポイントの挙動を確認することができない

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

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

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

さいごに

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