みなさん、MuleSoftはご存じでしょうか。
MuleSoftは、様々なシステム間連携をハブ＆スポーク型でつなぎ合わせるiPaaS（Integration Platform as a Service）製品です。
私たちのチームでは、このMuleSoftを主軸として様々なプロジェクト支援を行っており、最近では、MuleSoft開発においても生成AIを使った開発効率化が注目されています。
この記事では、その一例としてGitHub Copilotを使って、OpenAPI定義（以降、OAS: OpenAPI Specification）を作成するMuleSoft開発をご紹介します。
この記事の目的
この記事は、OASを知らない方でもOASを効率的に作成できるようになることを目的としています。
従来のExcel設計書に代わる形で、APIの仕様をコードとして管理する現代的な開発手法を、生成AIの力を借りて習得していただけると幸いです。
従来のExcel設計書が抱える課題
従来、IF（インターフェース）仕様書などの設計書をExcelで記載してきた方も多いのではないでしょうか。
Excelは誰にでも扱いやすいユーザーフレンドリーなツールではありつつも、システム開発においては以下のような課題があることも事実です。
- バージョン管理の困難さ：Git等の構成管理に不向きで、大規模開発における変更管理や差分確認が難しい。
- 見た目のブラッシュアップが必要：お客様レビュー向けの見た目上の作りこみなど、設計と直接関連しない部分にも作業時間がかかる。
- 自動化のしづらさ：ドキュメントの構造が開発者に任せられているため、設計書からのソースコード・テストコードの自動生成が難しい。
これに対し、コード化された設計書であれば、バージョン管理がしやすく、様々な自動生成ツールも活用しやすくなります。
OASと生成AIの活用
これらの課題に対して、OASは非常に効果的です。
IF仕様をコードベース（YAML形式）で記述し、そこからドキュメントやソースコード・テストコードを自動生成できます。
ただし、OASにもOAS記法の学習コスト、複雑な仕様定義を行う際の記述ミスなど、いくつかの課題があります。
これらの課題を緩和・解消するのがGitHub CopilotのようなAIコーディングツールです。
AIコーディングを併用することで、OASの課題を以下のように解決することができます。
- 自然言語での仕様記述：専門的な記法を知らなくても、チャットベースで要件を伝えることでOASを生成できる。
- 学習コストの大幅削減：OAS記法を一から学ぶ必要がなく、すぐに実用的なAPI仕様を作成できる。
このように生成AIの活用により、従来の課題を解決しながら現代的な開発手法を導入することができます。
必要なツール
本記事では以下のツールを使用します。
| ツール名 | 用途 | 動作確認バージョン | 備考 |
|---|---|---|---|
| Visual Studio Code（VS Code） | IDE | 1.104.1 | 最新版推奨 |
| GitHub Copilot | AIによるコード生成 | 4.11.0 | 有効化済みアカウントが必要 |
| Anypoint Code Builder - API Extension | OAS作成支援 | 最新版（2025年10月時点） | VS Code拡張機能 |
Anypoint Code Builder - API Extension とは？
Anypoint Code Builder - API Extensionは、MuleSoft開発に特化したVS Codeの拡張機能です。
OASの作成・編集において以下の機能を提供します。
- リアルタイムプレビュー：OAS記述と同時にAnypoint Design Center形式での表示
- シンタックスハイライト：YAML/JSON形式のOAS記述をサポート
- バリデーション機能：OAS記述の構文エラーや仕様違反をリアルタイムで検出
- MuleSoft統合：Anypoint Platformとの連携機能
セットアップ手順
Step 1: プロジェクトの作成
拡張機能のインストール後、Welcome画面から 「Quick Actions → Design an API」 を選択します。
Step 2: APIプロジェクトの設定
新規プロジェクトの作成画面で、プロジェクトの基本情報を入力します。
| 項目 | 説明 | 例 |
|---|---|---|
| Project Name | プロジェクト名（英数字・ハイフンのみ） | openapi-sample |
| Location | プロジェクトの保存場所 | （任意の場所） |
| API Specification | API仕様を選択 | OpenAPI 3.0 (YAML) |
Step 3: 開発環境の確認
プロジェクトが作成されると、以下の構成でファイル群が自動生成されます。
openapi-sample/
├── openapi-sample.yaml # メインのOAS定義ファイル
└── exchange.json # Anypoint Exchange用設定ファイル
これでOAS執筆の準備が完了しました！
右上のAPI Consoleのアイコンを選択すると、プレビュー画面が表示され、リアルタイムでAPI仕様を確認できます。
OASを書いてみよう！
この状態でもOASの執筆は可能で、Swagger UI形式でのライブプレビューも確認できます。
しかし、普段からOASを書き慣れている人であればこれで十分ですが、今回の主題は脱Excelのために設計書をコード化することが目的です。
OASはそれほど難しくありませんが、OASを知らない方にとって完全にフレンドリーとは言い切れません。
生成AIを活用したアプローチ
そこで生成AIを活用します。OASを知らない方でも自然言語でAPI仕様を伝え、生成AIにOASの執筆を依頼するイメージです。
例えば、以下のようなプロンプトでGitHub Copilotに依頼してみましょう。
ユーザー情報を取得するGET APIを作成してください。
- パス: /users/{userId}
- レスポンス: ユーザー名、メールアドレス、作成日時を含む
- エラー: 404 Not Found、500 Internal Server Error
このように自然言語で仕様を伝えると、GitHub Copilotが適切なOAS形式で提案してくれます。
paths:
/users/{userId}:
get:
summary: ユーザー情報を取得
description: 指定されたユーザーIDに基づいてユーザー情報を取得します
parameters:
- name: userId
in: path
required: true
description: 取得対象のユーザーID
schema:
type: string
responses:
'200':
description: ユーザー情報の取得に成功
content:
application/json:
schema:
type: object
properties:
username:
type: string
description: ユーザー名
email:
type: string
format: email
description: メールアドレス
createdAt:
type: string
format: date-time
description: 作成日時
'404':
description: ユーザーが見つかりません
'500':
description: サーバー内部エラー
内容に不備がある場合は、プロンプトを工夫して「指示→修正→確認」のサイクルを繰り返すことで、OASを知らない方でもOASを生成できます。
また、生成されたOASをライブプレビューでドキュメントベースで確認することで、YAMLファイルとにらめっこすることなく、生成結果に問題ないかを確認することができます。
GitHub Copilotを使ったOAS編集の実践
それでは実際にGitHub Copilotを使ってOASを編集してみましょう。
まず、シンプルなプロンプトから試してみます。
/hello エンドポイントのGETメソッドを追加してください。
レスポンスはHello Worldメッセージを返すようにしてください。
GitHub Copilotが以下のようなコードを提案してくれます。
paths:
/hello:
get:
summary: Hello Worldメッセージを返す
description: 簡単なHello Worldメッセージを返すエンドポイント
responses:
'200':
description: 成功レスポンス
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: "Hello World"
example:
message: "Hello World"
ここから、より細かい仕様を指定してみましょう。
GET /hello にRequest Parameterのidフィールドを追加してください。
idフィールドの制約は以下の通りです。
- 最大32文字の文字数制限
- 必須項目として設定
- 1文字以上の最小文字数制限
paths:
/hello:
get:
summary: Hello Worldメッセージを返す
description: 簡単なHello Worldメッセージを返すエンドポイント
parameters: # ← 新しく追加
- name: id
in: query
required: true
description: ユーザーID
schema:
type: string
minLength: 1
maxLength: 32
example: "user123"
responses:
'200':
description: 成功レスポンス
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: "Hello World"
example:
message: "Hello World"
このように、具体的な制約や詳細な要件を自然言語で伝えることで、OASに習熟していないエンジニアでも、業務要件を充足するAPI仕様を効率的に作成できます。
カスタムインストラクションで精度アップ
上記の方法でも十分実用的ですが、さらに一歩踏み込んだアプローチをご紹介します。
前述のチャットベースでインタラクティブにプロンプトを与えていく方法には、以下の課題があります。
- 作業効率の問題： 生成結果が期待どおりにならず、何度も修正の指示を与えなくてはいけない可能性がある。
- スケーラビリティ： 複数のAPIがある場合の一括生成がしづらい。
- 精度・安定性の問題： 開発者の与えるプロンプトによって生成結果にばらつきが出る。
これらの問題を解決するため、カスタムインストラクションを活用します。
カスタムインストラクションとは、GitHub Copilotに対して事前に詳細な指示や規則を与える機能です。
カスタムインストラクションの設定方法
カスタムインストラクションの設定方法は複数ありますが、今回はプロジェクトルートに配置するインストラクションファイル（.github/copilot-instructions.md）を使用します。
このファイルに「ルール」や「出力フォーマット」を定義しておくと、どのメンバーでも一貫した品質のOASを生成できます。
カスタムインストラクションファイルの例
# Copilot Instructions
あなたはOpenAPI 3.0の仕様に精通したエンジニアです。
入力として与えられたMarkdown形式のAPI定義書を解析し、以下の制約と変換ポリシーに従い、正確かつ一貫性のあるOpenAPI 3.0準拠のYAMLを出力してください。
入力のMarkdown形式のAPI定義書は、`./interface`ディレクトリに配置されています。
## 制約
### 基本方針
- 入力は**Markdown形式**のAPI定義書（エンドポイント、パラメータ、レスポンス、エラー情報を含む）
- 出力は**OpenAPI 3.0**準拠のYAML形式
- **日本語でのdescription**（OASを知らない方が理解しやすいように）
- **具体的なexample**を必ず含める
### 技術仕様
- HTTPメソッド、パス、パラメータ、リクエストボディ、レスポンスを正確にマッピング
- パラメータの型（`string`, `integer`, `boolean`, `array`, `object`）を適切に設定
- 必須パラメータは`required`配列に正しく記載
- レスポンスのステータスコードと内容を正確に反映
## 変換ポリシー
### 1. フィールド命名規則
- **フィールド名は原則そのまま使用**（例：`update_at` → `update_at`のまま）
- 明白な表記ゆれがある場合のみ正規化（`update_at` → `updated_at`）
- 正規化した場合は元の名前を`x-originalField`で保持
### 2. 型マッピング規則
| Markdown記述 | OpenAPI型 | 備考 |
|-------------|-----------|------|
| `string` | `type: string` | そのまま |
| `int` | `type: integer` | 範囲制約があれば`minimum`/`maximum`追加 |
| `boolean` | `type: boolean` | そのまま |
| `datetime` | `type: string, format: date-time` | RFC3339形式 |
| `array` | `type: array, items: {type: string}` | 要素型が不明な場合のデフォルト |
### 3. 品質向上のための追加事項
- 全てのプロパティに日本語の`description`を追加
- 実用的な`example`値を設定
- エラーレスポンスには適切な`description`を記載
入力用設計書の準備
カスタムインストラクションとは別に、OASのもとになる設計書を用意し、GitHub Copilotにインプットすることも可能です。
このアプローチは、たとえば、既存のAPI仕様がExcelで管理されており、Excel設計書をもとにOASを生成したい場合などに有効です。
以下は今回使用する商品管理APIの設計書例です。
# インターフェース定義書
## 基本情報
| システム名 | アプリケーション名 | Version |
|-----------|----------------|---------|
| 商品管理システム | item-api | 1.0.0 |
### 概要
商品IDを指定した商品情報の取得や作成、商品名・説明・タグなどの条件による商品検索等のAPIを提供します。
## API一覧
| API名 | HTTPメソッド | パス | 説明 | レスポンスステータス |
|-------|-------------|------|------|---------------------|
| 商品取得 | GET | /items/{itemId} | 指定した商品の詳細情報を取得 | 200, 400, 404, 500 |
| 商品一覧取得 | GET | /items | 条件に基づく商品一覧を取得 | 200, 400, 500 |
| 商品作成 | POST | /items | 新しい商品情報を作成 | 201, 400, 500 |
## 詳細仕様
### GET /items/{itemId}
#### パラメータ
| パラメータ名 | 場所 | 型 | 必須 | 説明 |
|-------------|------|-----|------|------|
| itemId | path | string | ○ | 商品ID（最大50文字） |
### POST /items
#### リクエストボディ
| フィールド名 | 型 | 必須 | 説明 | 制約 |
|-------------|-----|------|------|------|
| name | string | ○ | 商品名 | 最大100文字 |
| price | number | ○ | 価格 | 0以上の数値 |
| description | string | - | 商品説明 | 最大500文字 |
## データモデル
### Item（商品情報）
| フィールド名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| id | string | ○ | 商品ID |
| name | string | ○ | 商品名 |
| price | number | ○ | 価格 |
| description | string | - | 商品説明 |
| createdAt | string | ○ | 作成日時 |
Markdownファイルから自動でOASを生成する
自動生成を実行するにあたり、以下のフォルダ構成でプロジェクトを整理しました。
openapi-sample/
├── .github/
│ └── copilot-instructions.md # カスタムインストラクションファイル
├── interface/
│ └── item-api-spec.md # 入力用のMarkdown設計書
├── openapi-sample.yaml # メインのOAS定義ファイル（出力先）
└── exchange.json # Anypoint Exchange用設定ファイル
カスタムインストラクションが設定された状態で、以下のプロンプトを実行します。
.github/copilot-instructions.mdに則りOASを生成してください。
生成結果例（長いのでたたみます）
openapi: 3.0.0
info:
version: 1.0.0
title: 商品管理API
description: 商品IDを指定した商品情報の取得や作成、商品名・説明・タグなどの条件による商品検索等のAPIを提供します。
paths:
/items/{itemId}:
get:
summary: 商品取得
description: 指定した商品IDに基づいて商品の詳細情報を取得します
parameters:
- name: itemId
in: path
required: true
description: 取得したい商品の一意識別子（最大50文字）
schema:
type: string
maxLength: 50
example: "item-12345"
responses:
'200':
description: 商品情報の取得に成功しました
content:
application/json:
schema:
$ref: '#/components/schemas/Item'
'400':
description: リクエストパラメータが不正です
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 400
message: "商品IDの形式が正しくありません"
'404':
description: 指定された商品が見つかりません
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 404
message: "商品が見つかりません"
'500':
description: サーバー内部エラーが発生しました
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 500
message: "内部サーバーエラー"
/items:
get:
summary: 商品一覧取得
description: 条件に基づいて商品一覧を取得します
responses:
'200':
description: 商品一覧の取得に成功しました
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Item'
example:
- id: "item-12345"
name: "サンプル商品"
price: 1000
description: "これはサンプル商品です"
createdAt: "2025-10-09T10:00:00Z"
'400':
description: リクエストパラメータが不正です
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 400
message: "検索条件が不正です"
'500':
description: サーバー内部エラーが発生しました
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 500
message: "内部サーバーエラー"
post:
summary: 商品作成
description: 新しい商品情報を作成します
requestBody:
required: true
description: 作成する商品の情報
content:
application/json:
schema:
type: object
required:
- name
- price
properties:
name:
type: string
maxLength: 100
description: 商品名（最大100文字）
example: "新商品"
price:
type: number
minimum: 0
description: 商品の価格（0以上の数値）
example: 1500
description:
type: string
maxLength: 500
description: 商品の詳細説明（最大500文字、任意項目）
example: "この商品は高品質で使いやすい商品です"
responses:
'201':
description: 商品の作成に成功しました
content:
application/json:
schema:
$ref: '#/components/schemas/Item'
'400':
description: リクエストボディが不正です
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 400
message: "商品名は必須です"
'500':
description: サーバー内部エラーが発生しました
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 500
message: "内部サーバーエラー"
components:
schemas:
Item:
type: object
required:
- id
- name
- price
- createdAt
properties:
id:
type: string
description: 商品の一意識別子
example: "item-12345"
name:
type: string
description: 商品名
example: "サンプル商品"
price:
type: number
description: 商品の価格
example: 1000
description:
type: string
description: 商品の詳細説明（任意項目）
example: "これはサンプル商品の説明です"
createdAt:
type: string
format: date-time
description: 商品が作成された日時（RFC3339形式）
example: "2025-10-09T10:00:00Z"
Error:
type: object
required:
- code
- message
properties:
code:
type: integer
description: エラーコード
example: 400
message:
type: string
description: エラーの詳細メッセージ
example: "リクエストが不正です"
このように細かく指示をしなくても、簡単なプロンプトでGitHub Copilotが自動的にMarkdownの内容を解析し、適切なOAS形式のYAMLファイルを生成してくれます。
この手法により、以下のようなメリットを得られます。
- 精度・安定性の向上: カスタムインストラクションにより生成結果の一貫性・再現性を高めることができます。
- 作業効率の向上: 手動でのOAS作成と比較して、大幅に作業時間を短縮できます。
- 脱Excel： Markdown形式の設計書により、バージョン管理との親和性が向上
さいごに
この記事では、MuleSoft Anypoint ExtensionsとGitHub Copilotを活用してOASを効率的に作成する方法をご紹介しました。
これらの手法を活用することで、OASを知らない方でも現代的なAPI開発の流れに参加できるようになります。
すでにOASを積極的に記述している方にも品質の一貫性や効率的な開発に寄与できれば幸いです。
ぜひ実際のプロジェクトで試してみてください！
NTT DATA公式アカウントです。 技術を愛するNTT DATAの技術者が、気軽に楽しく発信していきます。 当社のサービスなどについてのお問い合わせは、 お問い合わせフォーム nttdata.com/jp/ja/contact-us/ へお願いします。