はじめに

みなさん、こんちは torihaziです。

OpenAPIは知っていますか？

OpenAIではないです。

自分は言葉だけしか知らないです。

ふんわり程度。

ただこのままでは良くないと思い、色々勉強してみました。

Railsから色々操れるようになるまでがゴールです。

追記: 雰囲気までは掴めた。rspecについてほぼ忘れているのでそっちをまず入れたほうが良さそう。

はじめに
どのようなものか
参考資料

どのようなものか

まずOpenAPIとは何か。

資料によると APIの仕様を記述するためのフォーマットであるらしい。これを使用することでAPIの仕様をドキュメント化でき、APIエンドポイントの実コードを観に行かなくてもよくなるらしい。

確かにfrontend側の人間が APIを叩いてどんな情報がもらえるか、渡せば良いかだけ知れれば話は早そう。

また認識合わせの際にも楽そう。

OpenAPI自体はYAML or JSONで書くものらしく、公式docもあるみたい。

書き方も色々決まっているらしいが、versionもあるらしい。

これを書けばある種の自動化もいけるらしい、そしてそれをどのようにrailsの開発に転用できるのかはまだ未知数。

docに落とせるから version管理もできる、故に差分検知がしやすい。

もう少し資料を漁ってみる。

ググったら、色々出てきた

RESTAPIのインターフェースの仕様を記述したもの」
APIの設計、開発、ドキュメント化、利用を標準化する仕組み
ドキュメント化しているのでコミュニケーションが取りやすい。

少し言語化して整理

OpenAPIは RESTAPIインターフェースの仕様を標準化、可視化することでシステムの開発効率を上げるための仕組みである

となるのかな？狭義では フォーマットとされていたりするから IT特有の文脈によって意味が変わる感じかな。

とにかく個人的に上の言語化がしっくりきた。

ということであるべき理由について概要を掴んだから今度は使い方か。どのように使えば恩恵を受けられるのか。

と思ったけど Swaggerというものも出てきたな。

これとの関係性はなんだ？

これについてもググってみるか。

元々はSwaggerという名称でしたが、2015年にOpenAPI Initiativeに寄贈されてからOpenAPIと呼ばれるようになり、現在は「Swagger」はOpenAPI仕様に基づいたツールのセットを指す

であるそうだ。

OpenAPI仕様のものを楽に作れるようになる便利セットなのかな？

Swagger: OpenAPI仕様を基に作られた、API開発、文書化、テストのためのツールのセット。
Swagger Editor: OpenAPI定義書の編集ツール。
Swagger UI: OpenAPI定義書からUI形式のドキュメントを生成するツール。
Swagger Codegen: OpenAPI定義書からコードを自動生成するツール。

ほー。

色々あるのね。

ツールが色々あるみたい。

今思ったが、やっぱり OpenAPIというのは特定のフォーマットを指すのか？

システム開発の効率化というのは特定のフォーマットにすることによって得られる副産物であるから。

claudeに聞いてみてもやっぱりフォーマットっていう言語化の方が良いみたい。

OpenAPIは、REST APIインターフェースの仕様を記述するための標準化されたフォーマットである

OpenAPI = フォーマット = 決まった書き方・記法という理解で良さそう。

ということでツール紹介

Stoplight Studio OpenAPIに則ったdocをGUIで簡単に作成することができるツールみたい。
Redoc OpenAPIに則ったdocをHTMLベースで生成、成果物を閲覧することができるツールみたい。Swagger UIに近しいそう。
Prism OpenAPIに則ったdoc(YAML形式)を読み込ませることでモックサーバを作ることができるツールみたい。
OpenAPI Generator OpenAPIに則ったdocから APIサーバ / フロントエンドのコードを自動生成してくれるツールみたい。

色々ツールがあるんやな。

で OpenAPIの公式 docを見てみる。

OpenAPI = OAS = OpenAPI Specificationらしい。

歴史的には Swaggerというものだったけどそれが色々あって OpenAPI Specificationになったそう。

OK、多分背景情報は理解できたはず。

ここからは実際の書き方についてみてみる。

まずはCRUDのOpenAPI仕様書を書いてみるとするか。

githubみてみた。

githubの説明が一番的を得ていたきがした。綺麗で完結、過不足ない言語化だったと思う。

で公式の書き方docがこれか

なんかちらっとversionで書き方が違うとか言っていたから多分これもキャッチアップコストかかるんだろうな。

んーー、情報としては正しいと思うが、長すぎてまるでわからん。

成果物としてどのようなものができて、とかから始めた方が良い。

ということでzennやqiitaを漁る。

記述形式は YAML or JSONで。

Swagger Editorを使用すれば相互変換が可能とある。

sample.ymlという感じ。ファイル名に命名規則はない感じかな？

openapi: 3.0.0
info:
  ...
servers:
  ...
paths:
  ...
components:
  ...
security:
  ...
tags:
  ...
externalDocs:
  ...

ていうかこのyamlにおいて openapiとかinfoってどういう呼び方だっけ。

key ? jsonだったら keyとvalueという呼び方だったけど、qiita曰くオブジェクトという感じか？フィールドか。

まぁそこはそんなに問題じゃないか。keyだとラベルの名前みたいなイメージだけどフィールドだとまとまりみたいなイメージがあるから

そんな感じでいいか。

でエンドポイントのメインになりそうなのが pathsフィールド。

ここに実際の /users に getでアクセスしたらこのような httpステータスコードと response を返しますよという感じになるのね。

tagsフィールドで定義して paths のtagに記述すると 見せる上でグルーピングして表示できるようになるのね。

components フィールドで記載する内容がモデルを表すそうだけどふーんんという感じか。

securityも大事だけど、ね。って感じや。

一旦わかったので書いてみるか。

Railsで使ってみよう。

ググる。

gemを使うと思うが、一覧で示して欲しいな。

というか Railsの開発に OpenAPIを取り入れる上で考え方が二つあるみたい。

Integrating OpenAPI with a Ruby on Rails application can be achieved through various methods, primarily focusing on either generating OpenAPI documentation from your existing code (code-first) or using an OpenAPI specification to guide your development and testing (design-first).

code-firstかdesign-first

既存のrailsコードからOpenAPI docを作って取り入れるのか、OpenAPI docを使って開発などを効率的に進めるのか。

今回は効率的とか既存とかもない。ただ、普通に使ってみたいだけなので、あんま気にしない。

知りたいのは一から自分でrails 上の1ファイルとして OpenAPI準拠のYAMLファイルを書くのかそれともRailsウェイにある程度乗っかりながら記載できるのかということ。

rspec使って生成できるとかいうのはどこかで聞いたことある。

OpenAPI Rails とかで調べて片っ端から列挙していく

committie readmeにも書かれてない。何ができて、何の目的で入れるのか。どのように使うのかは書いているけど。
rswag rspecのrequest specを拡張して rswag独自の書き方で書くことによってOpenAPI docをYAML or JSON形式で出力できるまたdocを作った後のビジュアライズもswagger-uiを通していけるそうな？なんかこれ使っておけば良さそう。 swaggerの仕組みをrails way に載せてくれる gemとみた。

あと rspecのいろはを忘れているわ。

まぁいいかその都度入れてこう。

readmeをclaudeに食わせて要約

1. テストを書くと仕様書が自動生成される
RSpecという普通のテストを書くだけで、OpenAPIファイル(YAMLやJSON)が自動で作られる
2. テストと仕様書が一体化
テストコードの中にAPI仕様を書くから、テストと仕様書がズレない
3. Swagger UIが使える
自動生成した仕様書から、ブラウザで見られる綺麗なAPIドキュメントページが作れる

なるほど、そろそろ書いてみるか

適当にscaffold

# ブログ記事API
rails generate scaffold Post title:string content:text published:boolean

# ユーザーAPI
rails generate scaffold User name:string email:string

# コメントAPI
rails generate scaffold Comment post:references content:text

なんとなくわかった。

ただこれは rspecにある程度習熟してからのほうが良さそう。