OpenAPI とは？

混同されやすいけど、厳密には別物だよ。OpenAPIはAPI仕様の標準フォーマット（仕様）で、Swaggerはその仕様を扱うためのツール群（エディタ・UI・コードジェネレーターなど）のことなんだ。もともとSwagger仕様と呼ばれていたものがOpenAPI仕様に改名されたという歴史があるよ。

エンドポイントのパス・HTTPメソッド・パラメータの型・リクエスト・レスポンスのスキーマ・認証方式・エラーのパターンなどを書くんだ。「GETで `/users/{id}` を叩いたらUser型のJSONが返る」みたいな情報を機械が読める形式で記述するよ。

openapi-generatorというツールを使うと、OpenAPI仕様書からTypeScript・Python・Go・Javaなどのクライアントコードを自動生成できるよ。APIを変更するたびに仕様書を更新して再生成することで、クライアントとサーバーの型の齟齬を防げるんだ。

そっちの方向もあって、「コードファースト」と呼ぶよ。FastAPIやNestJSなどのフレームワークはコードを書くとOpenAPI仕様書を自動で生成してくれる。一方「仕様ファースト」はOpenAPIを先に書いてからコードを実装する方法で、チームでAPIの設計を先に合意したいときに向いている。どちらが正解かはチームの流儀によるんだけど、仕様書とコードが乖離しないように管理するのが一番大変だよ。

GraphQLを使う場合はGraphQLスキーマ自体がAPI仕様書になるからOpenAPIは不要。gRPCならProtocol Buffers（.protoファイル）が仕様書。REST API以外の選択肢が増えているけど、REST APIを使うならOpenAPIはデファクトスタンダードだよ。