OpenAPIとRuby on Railsを組み合わせた開発
Introduction
OpenAPIを使用してAPIの設計とドキュメンテーションを行う方法を学び、
Ruby on Railsと統合するスキーマ駆動開発について紹介します🧑💻
Goal
- OpenAPIについて知っていただく
- なぜドキュメントが必要なのか？
- Ruby on Railsと組み合わせるメリットについて
Target
- Ruby on RailsおよびRspecの経験がある開発者
- OpenAPIについての初心者
What is OpenAPI?
OpenAPIは、API仕様を記述するためのフォーマットであり、APIの設計とドキュメンテーションを行うための標準です。
OpenAPIを使用することで、以下のことが実現できます。
- APIの設計を標準化し、誰でも理解しやすくする
- APIエンドポイント、リクエスト、レスポンスなどを文書化する
- クライアントとサーバー間でコミュニケーションを効率化する
Why use OpenAPI?
上記でも触れましたが、OpenAPIを使用する事(APIをドキュメント管理すること)で以下のメリットが生まれます。
- コニュニケーションの円滑化
- APIを使用するクライアントとの間で認識をドキュメントで合わせることができる
- 自動化とツールの活用
- OpenAPIのドキュメントからソースコードを自動生成ができる
- テストと組み合わせた開発を行うことができる
- バージョン管理
- APIのバージョンや変更をドキュメントで管理することができるため、Gitなどで差分を容易に確認することができる
- コニュニケーションの部分にも関わるが、変更する点をドキュメントで事前に確認することができる
OpenAPI Structure
OpenAPIドキュメントはYAMLまたはJSON形式で記述されます。
基本的な構造は以下の通りです。
openapi: 3.0.0
info:
title: タイトル
version: バージョン
paths:
/endpoint:
get:
summary: エンドポイントの説明
responses:
'200':
description: 成功した場合のレスポンス
content:
application/json:
schema:
type: object
properties:
propertyName:
type: string
-
openapi:使用しているOpenAPIのバージョン -
info:APIの情報（タイトル、バージョンなど） -
paths:APIのエンドポイントとそれに関連する操作（GET、POSTなど） -
responses:各操作のレスポンスが定義され、その中には成功およびエラーレスポンスが含まれる
Swagger Editorというツールを使用することで上記のドキュメントをプレビューすることができます。
バージョンによって構造や定義が異なる部分がありますが、詳細はOpenAPIのドキュメントを参照してください。
参考に、OpenAPI V3では以下のデータ型が存在します。
| データ型 | フォーマット | 説明 | 例 |
|---|---|---|---|
| string | - | 文字列 | "Hello, World" |
| string | date | 日付 | "2023-10-11" |
| string | date-time | 日時（ISO 8601形式） | "2023-10-11T15:00:00Z" |
| string | password | パスワード | "secretpassword" |
| number | - | 数値（浮動小数点数も含む） | 42, 3.14 |
| integer | - | 整数 | 42 |
| boolean | - | 真偽値 | true, false |
| object | - | オブジェクト | {"key": "value"} |
| array | - | 配列 | ["item1", "item2"] |
| null | - | ヌル値 | null |
| enum | - | 列挙型 | ["red", "green", "blue"] |
| any | - | 任意のデータ型 | 任意のデータ |
| binary | - | バイナリデータ | base64エンコードされたバイナリデータ |
Practice
実際にSwagger EditorにアクセスしてOpenAPIのドキュメントを作成してみましょう！！
Integration with Ruby on Rails
OpenAPIとRuby on Railsの連携について紹介します。
Committee
committeeはOpenAPI 2.0 / Swagger 2.0またはOpenAPI 3.0 / Swagger 3.0形式のAPI仕様に基づいてAPIリクエストおよびレスポンスを検証し、テストすることができます。
今回はこちらに焦点を絞って紹介します
主な機能
- APIバリデーション
- APIリクエストとレスポンスがAPIドキュメントに準拠しているかを検証ができる
- テストサポート
- Rspecなどのテストフレームワークと統合してAPIドキュメントと一致しているかのテストを作成できる
- Midlewareとしての使用
- Rackミドルウェアとしてアプリケーションに統合できる
- カスタマイズが可能
- 特定のバリデーションルールを設定したり、エラーメッセージをカスタマイズしたりできる
rswag
Ruby on RailsのプロジェクトでAPIのテストとドキュメンテーションを行うためのツールです。rswagはRSpecとSwagger（OpenAPI）仕様に基づいてAPIテストを記述し、Swagger形式のAPIドキュメンテーションを生成することができます。
主な機能
- APIテストの記述
- APIドキュメントの自動生成
- リクエスト及びレスポンス例の自動生成
- Swagger UIの提供
- APIドキュメントのエクスポート
- 生成したドキュメントを外部ツール、サービスにエクスポートできる
こちらは今回検証していないですが、良さそうなツールなのでまた別の機会で触ってみます。
Practice
実際にCommitteeを使用したRspecの実装例を体験してみよう！
サンプルリポジトリを作成したので、こちらから環境を構築してRspecを実行してみよう！
実行サンプル
OpenAPIの定義には zip_code が必須として定義されていますが、レスポンスに含まれていないのでエラーになります。
OpenAPIの定義
Rspec実行結果
実際のレスポンスサンプル
Closing Remarks
今回はOpenAPIの概要とRuby on Railsとの連携について実習を踏まえて解説しました。
Committeeを使用する部分はRspecでのレスポンスチェックしか行わなかったので、また今度他の使い方についても記事にしようかと思います。
また、今回は触れませんでしたがOpenAPIの定義を利用してTypeScriptなどの型定義を自動生成することができるので、フロントエンドとの連携についてもかなりのメリットが生まれます。
こちらのついてもまた検証して記事にしようかと思います。
最後までありがとうございました！
Discussion