OpenAPI_Generator_ゼロから入門

新人エンジニア向け ｜ 図解でゼロからわかる OpenAPI Generator ゼロから入門 「API」を知らなくても大丈夫。図解だけで最後までたどり着けます。 仕様書 うさうさ研修工房 ツール コード

AGENDA この教材で歩く道のり 0 1 2 3 4 そもそも「 API」って何？ まずはAPI・仕様書の基本イメージから 仕様とコードがズレる問題 なぜOpenAPI Generatorが必要になるのか OpenAPI Generatorの全体像 仕組みを図で丸ごと理解する 基本の使い方 インストール〜コマンド〜生成結果まで つまずきポイントと対策 初心者がやりがちなミスを先回りで回避 OpenAPI Generator ゼロから入門 2

STEP 0 ｜ そもそも 「API」とは、アプリ同士の “会話”のルール ① リクエスト（お願い） 「田中さんの情報をください」 あなたのアプリ （フロントエンド） ② レスポンス（お返事） 「はい、これが田中さんのデータです」 サーバー （バックエンド） API（Application Programming Interface）とは、この「お願い」と「お返事」のやりとりを成立させる窓口・ルールのこと。買い物でいう「レジでの注文の仕 方」に近いイメージ。この“会話のルール”を人間にも読める形で書き表したものが、次に出てくる「仕様書（ OpenAPI）」です。 OpenAPI Generator ゼロから入門 3

STEP 0 ｜ そもそも 「仕様書」＝フロントとバックの “共通ルールブック ” フロント担当者 バック担当者 「どんな形の データが来るの？」 「どんな形で データを返そう？」 仕様書 （OpenAPI） 仕様書には「このURLに、この形でお願いすると、この形でお返事が返ってくる」というルールがすべて書かれています。フロントとバックが別々に「思い込 み」でコードを書くのではなく、この1枚のルールブックを両者で共有することが、ズレをなくす第一歩です。 OpenAPI Generator ゼロから入門 4

STEP 0 ｜ そもそも 仕様書は「 YAML」という書式で書く paths paths: /users: どのURL（住所）にアクセスするかを書く場所 get: summary: ユーザー一覧取得 get responses: '200': どんな操作（取得・登録など）をするか content: application/json: schema: type: array OpenAPI Generator ゼロから入門 responses 返ってくるデータの形を定義する場所 5

STEP 1 ｜ 課題を知る でも実際は …仕様とコードがズレていく 仕様書に書かれた型 実際に返ってきた JSON name: string name: string age: number age: "20"（文字列！） 型が違う！ 67.11% 公開OpenAPI仕様2,529件を分析した 査読済み研究（ Decrop & Vandeloise, 2026）でも、公開されている仕様書の平均品質は約 67%にと どまり、規模が大きい APIほど仕様と実装の「意味的なギャップ」が広がりやすいと報告されていま す。仕様書は書いて終わりではなく、実装との一致を保ち続ける工夫が必要です。 平均ドキュメント品質スコア OpenAPI Generator ゼロから入門 6

STEP 2 ｜ 全体像 解決策：仕様書から “自動で”コードを作る クライアントSDK サーバースタブ OpenAPI仕様 （YAML） OpenAPI Generator ドキュメント ポイント：仕様書を1回書けば、あとはコマンド1つで複数の成果物が同時に作れる。手作業の写し間違いと 設定ファイル いう「人的エラーの発生源」自体をなくす発想。 OpenAPI Generator ゼロから入門 7

STEP 2 ｜ 全体像 中では何が起きている？（ 3ステップ） ① 仕様を読み込む ② テンプレートに当てはめる ③ コードを出力する YAMLファイルを解析し、パス・型・パラメータの 言語ごとに用意された雛形（Mustacheテンプ 完成したソースコード・ドキュメントをファイルとし 情報を取り出す レート）に情報を流し込む て書き出す OpenAPI Generator ゼロから入門 8

STEP 2 ｜ 全体像 生成される 4つの成果物 クライアント SDK サーバースタブ 20以上の言語向けにAPIクライアントライブラリを生成。フロントとバックの型齟齬 Java・Kotlin・Go・PHPなど40以上の技術に対応。新技術の評価コストを下げ を構造的に防ぐ。 る。 ドキュメント 設定ファイル 仕様書から人が読める形式のAPIドキュメントを自動生成し、実装との乖離を防 Apache2設定・MySQL／GraphQLスキーマなど、特殊な生成にも対応する拡 ぐ。 張性。 OpenAPI Generator ゼロから入門 9

STEP 2 ｜ 全体像 開発の流れ全体の中の位置づけ Design Generate Implement Test Document OpenAPI仕様を設計 コード自動生成 ロジックを実装 契約テストで検証 ドキュメント配布 OpenAPI GeneratorはDesignとImplementの「橋渡し」を担う。仕様が変われば、この橋の出力も自動的に更新される。 OpenAPI Generator ゼロから入門 10

STEP 3 ｜ 使ってみる 導入は3つの方法から選べる npmラッパー @openapitools/ openapi-generator-cli Dockerイメージ docker run Homebrew／JAR brew install openapitools/ openapi-generator-cli openapi-generator Node.jsに馴染む方法。 環境差異を気にせず、 ローカルに直接導入。 バージョンを openapitools.json CI/CD上でそのまま Javaプロジェクトのため で固定・共有できる。 実行できる。 Java環境が必要。 OpenAPI Generator ゼロから入門 11

STEP 3 ｜ 使ってみる 基本コマンドを分解してみる openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client -i -g -o input generator output 入力とする OpenAPI仕様ファイルのパス OpenAPI Generator ゼロから入門 使用するジェネレータ名（例： typescript-axios, spring） 生成コードの出力先ディレクトリ 12

STEP 3 ｜ 使ってみる コマンドを実行すると、何が生まれる？ ./client api.ts 仕様書に定義されたエンドポイントを呼び出す関数群 ├─ src/ │ ├─ api.ts │ └─ models/ models/ │ └─ User.ts ├─ README.md 仕様書のschemaから生成された型定義（インターフェース） ├─ package.json └─ .openapi-generator/ README.md └─ VERSION 生成コードの使い方ドキュメント（自動作成） OpenAPI Generator ゼロから入門 13

STEP 3 ｜ 使ってみる 現場でよく使われる組み合わせ フロントエンド typescript-axios React・Vue等のSPAからAPIを型安全に呼び出す バックエンド spring / go-server 仕様に沿った雛形コードから実装をスタート 社内SDK配布 java / python / kotlin 複数チームに同じ契約のクライアントを配布 ドキュメント html2 / markdown 仕様書を人が読みやすい形式で公開 OpenAPI Generator ゼロから入門 14

STEP 4 ｜ つまずき回避 初心者がやりがちなミスと、その対策 生成されたコードを直接編集してしまう 再生成すると変更が消えてしまう 仕様が頻繁に変わりすぎる 生成物のレビュー負荷が増大する oneOf・anyOfなど複雑な型を使う 一部ジェネレータで挙動が不安定になる OpenAPI Generator ゼロから入門 対策 .openapi-generator-ignoreで対象外指定、またはテンプレートを自作する 対策 契約が安定してから導入し、変更はPRレビューを必須にする 対策 対象ジェネレータの対応状況をGitHub Issueで事前確認する 15

まとめ 仕様書を正典に、コードは自動で作る APIは会話のルール、仕様書はそのルールブック OpenAPI Generatorは仕様書からコードを自動で作る翻訳機 生成コードは直接編集しない。テンプレートやignoreで運用する 仕様書自体の品質を確認する習慣が、ズレを防ぐ一番の近道 出典：OpenAPI Generator公式サイト（openapi-generator.tech）／ Decrop & Vandeloise (2026) OASQuali, Springer Nature OpenAPI Generator ゼロから入門 16