【公開】OpenAPI_Generator_入門研修

文系新人エンジニア向け IT研修教材 OpenAPI Generator 入門 API仕様書から「動くコード」を自動生成する ― 契約駆動開発（API-First）の基礎 OpenAPI仕様（契約） うさうさ研修工房 コード自動生成 査読済み研究に基づく解説

AGENDA 本日学ぶこと 01 02 03 04 Why なぜ今、API-First設計とコード自動生成が必要なのか What OpenAPI Generatorとは何か（機能・エコシステム） How 基本的な使い方と現場での運用のコツ Research 査読済み研究が示す仕様品質の課題と最新動向 OpenAPI Generator 入門研修 2

WHY ｜ なぜ学ぶのか フロントとバックエンドの「言った言わない」問題 新人がぶつかりやすいシーン 査読済み研究が示す実態 「ドキュメントの型と、実際に返ってきたJSONの型が違う…」 クライアント側とサーバー側で、同じレスポンスを毎回手で書き写してい る 67.11% 公開されているOpenAPI仕様2,529件を分析した結果の 平均ドキュメント品質スコア 仕様変更のたびに、手書きの型定義がドキュメントと少しずつズレていく また、公開APIコーパス全体を横断した調査でも、セキュリティ定義の欠落 ・未文書化パラメータ・仕様と実装の不一致が繰り返し確認されている。 出典：Decrop & Vandeloise (2026) OASQuali, Springer OpenAPI Generator 入門研修 3

WHY ｜ なぜ学ぶのか 解決策：仕様書を「唯一の正典」にする（ API-First） コードを書く前に OpenAPI仕様（契約）を先に確定させ、そこからクライアント／サーバー双方のコードを機械的に生成する開発スタイル。手作業の 写し間違いという「人的エラーの発生源」自体をなくす発想。 Before：コードファースト After：API-First 実装 → 事後的にドキュメント化 OpenAPI仕様 → 実装より先に確定 フロント・バック間で型定義を手で複製 仕様から型・クライアントを自動生成 ズレに気づくのは結合テスト以降 ズレはコンパイル時／生成時に検知 OpenAPI Generator 入門研修 4

WHAT ｜ 何であるか OpenAPI Generatorとは OpenAPI仕様（OAS）ファイルを入力として、APIクライアントライブラリ（SDK）・サーバー スタブ・ドキュメント・設定ファイルを自動生成する、コミュニティ主導のオープンソースツー ル。 50+ クライアント ジェネレータ Swagger Codegen からのフォーク 2018年、Swagger Codegen v2.3.1〜2.4.0の間で分岐。コミュニティ主導の開発体制・意思決定の透 明性を重視して独立プロジェクト化した。 OpenAPI 2.0／3.0／3.1に対応 40+ サーバー スタブ言語 CLI・npmラッパー・Dockerイメージ配布 出典： openapi-generator.tech（公式サイト）／ GitHub: テンプレートはMustacheベースで自由に上書き可能 OpenAPI Generator 入門研修 OpenAPITools/openapi-generator 5

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

WHAT ｜ 何であるか API開発ライフサイクルの中の位置づけ Design Generate Implement Test Document OpenAPI仕様を設計 OpenAPI Generatorで コード自動生成 ビジネスロジックを実装 契約テストで検証 ドキュメントを配布 ポイント：OpenAPI GeneratorはライフサイクルのDesignとImplementの「橋渡し」を担う。仕様が変われば、この橋の出力も自動的に更新される。 OpenAPI Generator 入門研修 7

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

HOW ｜ どう使うか 基本コマンド： generate openapi-generator-cli generate \ -i openapi.yaml -g typescript-axios -o ./client -i -g -o input generator output 入力とする OpenAPI仕様ファイルのパス 使用するジェネレータ名（例： typescript-axios, spring） 生成コードの出力先ディレクトリ 補足：list コマンドで対応ジェネレータ一覧を、config-help -g <name> で言語別の詳細オプションを確認できる。 OpenAPI Generator 入門研修 9

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

HOW ｜ どう使うか 運用でつまずきやすいポイントと対策 よくある失敗 起きること 生成コードを直接編集してしまう 再生成のたびに変更が消える 仕様が頻繁に変わりすぎる 生成物のレビュー負荷が増大する oneOf・anyOfなど複雑な型 一部ジェネレータで挙動が不安定になる OpenAPI Generator 入門研修 対策 .openapi-generator-ignoreで対象外指定、またはテンプ レートを自作する 契約が安定してから導入する／変更はPRレビューを必須 にする 対象ジェネレータの対応状況をIssueで事前確認する 11

RESEARCH ｜ 研究知見 仕様品質のばらつきは、査読済み研究でも指摘されている OASQuali（2026年） 公開されているOpenAPI仕様2,529件を5つの観点（形式・バージョン・メタ データ・サーバー情報・説明文/例）で自動評価。平均文書品質は67.11% にとどまり、APIの規模が大きいほど「意味的なギャップ」が広がる傾向を確 認した。 API仕様コーパス横断研究（ 2025年） 公開OpenAPIコーパスを横断した調査でも、セキュリティ定義の欠落・未文書 化パラメータ・仕様と実装のミスマッチが繰り返し確認されている。仕様駆動の あらゆる手法は「仕様の品質」に依存するため、生成前のバリデーションが実 務上重要になる。 Decrop, A., Vandeloise, M. (2026). OASQuali: Automated Quality Analysis of OpenAPI From REST to MCP: An Empirical Study of API Wrapping and Automated Server Generation Specifications. Springer Nature. for LLM Agents. arXiv (2025). OpenAPI Generator 入門研修 12

RESEARCH ｜ 研究知見 仕様からテスト・実装まで自動化する研究も進んでいる Ed-Douibi et al. (2018) REST APIの仕様（OpenAPI）から、テストケースを自動生成する手法 を提案。IEEE EDOC国際会議にて発表。 IEEE 22nd International EDOC Conference OpenAPI Generator 入門研修 Chauhan et al. (2025) LLMベースのマルチエージェントが OpenAPI仕様を作成し、そこから サーバーコードを生成、実行ログをもとに自己修正する API-First自動 化の枠組みを提案。 Tampere University, arXiv preprint 13

まとめ OpenAPI Generatorで、契約と実装のズレをなくす 仕様書（OpenAPI）を唯一の正典とし、コードは仕様から生成する 公開仕様の平均品質は約 67% ― まず仕様自体の妥当性を確認する習慣を持つ 生成コードへの直接編集は避け、テンプレートや ignoreファイルで運用する 参考文献・出典 ・OpenAPI Generator公式サイト．https://openapi-generator.tech／GitHub: OpenAPITools/openapi-generator（閲覧日：2026年8月） ・Decrop, A., Vandeloise, M. (2026). OASQuali: Automated Quality Analysis of OpenAPI Specifications. Springer Nature. ・Ed-Douibi, H., Cánovas Izquierdo, J.L., Cabot, J. (2018). Automatic Generation of Test Cases for REST APIs: A Specification-Based Approach. IEEE 22nd International EDOC Conference. ・Chauhan, S. et al. (2025). From Specification to Service: Accelerating API-First Development Using Multi-Agent Systems. Tampere University, arXiv preprint. ・From REST to MCP: An Empirical Study of API Wrapping and Automated Server Generation for LLM Agents. arXiv preprint (2025). OpenAPI Generator 入門研修 14

• https://openapi-generator.tech