---
title: OpenAPI_Generator_ゼロから入門
tags:  #openapi_generator  
author: [Yukiko](https://docswell.com/user/yukiko_it)
site: [Docswell](https://www.docswell.com/)
thumbnail: https://bcdn.docswell.com/page/9J293P8MER.jpg?width=480
description: OpenAPI_Generator_ゼロから入門 by Yukiko
published: August 26, 26
canonical: https://docswell.com/s/yukiko_it/5JWN21-2026-08-26-084828
---
# Page. 1

![Page Image](https://bcdn.docswell.com/page/9J293P8MER.jpg)

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


# Page. 2

![Page Image](https://bcdn.docswell.com/page/DEY4156PJM.jpg)

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


# Page. 3

![Page Image](https://bcdn.docswell.com/page/VJNY2NZM78.jpg)

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


# Page. 4

![Page Image](https://bcdn.docswell.com/page/YE9P1RZWJ3.jpg)

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


# Page. 5

![Page Image](https://bcdn.docswell.com/page/GE8D4W1RED.jpg)

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


# Page. 6

![Page Image](https://bcdn.docswell.com/page/LELM6NQ27R.jpg)

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


# Page. 7

![Page Image](https://bcdn.docswell.com/page/4JMY5X19JW.jpg)

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


# Page. 8

![Page Image](https://bcdn.docswell.com/page/PJR93NL979.jpg)

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


# Page. 9

![Page Image](https://bcdn.docswell.com/page/PEXQ4NW3JX.jpg)

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


# Page. 10

![Page Image](https://bcdn.docswell.com/page/3EK9ZNVNED.jpg)

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


# Page. 11

![Page Image](https://bcdn.docswell.com/page/L73WDVMZ75.jpg)

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


# Page. 12

![Page Image](https://bcdn.docswell.com/page/87DKP864JG.jpg)

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


# Page. 13

![Page Image](https://bcdn.docswell.com/page/VJPKN8YVE8.jpg)

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


# Page. 14

![Page Image](https://bcdn.docswell.com/page/2EVVKNGREQ.jpg)

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


# Page. 15

![Page Image](https://bcdn.docswell.com/page/57GLQK86EL.jpg)

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


# Page. 16

![Page Image](https://bcdn.docswell.com/page/4EQYKN92JP.jpg)

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