x-openapi-flow-mcp

OpenAPI は API を記述します。x-openapi-flow はそれを実行可能なワークフローに変換します — 開発者と AI エージェントのために。

openapi.x.json で API ワークフローを定義すれば、独自のクライアントやオーケストレーションロジックを書かずに実行できます

🚀 最初の 3 週間で 2,100 回以上ダウンロード！

⚡ 数秒で始める

npx x-openapi-flow init --suggest-transitions

これにより、API の実行方法を単に記述するだけでなく、宣言的に定義できる openapi.x.json ファイルが生成されます。

シンプルなコマンドひとつで、OpenAPI 仕様から API のライフサイクルが動き出す様子を確認できます

検証、ドキュメント作成、フロー対応 SDK の生成を自動で行います。

これは何ですか？

x-openapi-flow は OpenAPI 仕様をワークフローレイヤーで拡張します。

openapi.json → API を記述します
openapi.x.json → API の使い方（フロー）を記述します

API 呼び出しをオーケストレーションする命令型コードを書く代わりに、ワークフローを宣言的に定義して、どこでも実行できます。

x-openapi-flow は、OpenAPI 仕様に宣言的なステートマシンを追加します。

リソースのライフサイクルをモデル化し、有効な遷移を適用するとともに、ドキュメント、SDK、自動化向けのフロー対応成果物を生成します。

🚀 例

ステートフルなワークフローとライフサイクルの遷移を、OpenAPI オペレーション内に直接定義します。

{
  "operationId": "createOrder",
  "x-openapi-flow": {
    "version": "1.0",
    "id": "create-order",
    "current_state": "created",
    "description": "Creates an order and starts the lifecycle",
    "transitions": [
      {
        "transition_id": "order-created-to-paid",
        "trigger_type": "synchronous",
        "condition": "Payment is confirmed",
        "decision_rule": "payOrder:response.200.body.payment_status == 'approved'",
        "target_state": "paid",
        "next_operation_id": "payOrder",
        "operation_role": "mutate",
        "prerequisite_operation_ids": ["createOrder"],
        "evidence_refs": [
          "payOrder:response.200.body.payment_status"
        ],
        "propagated_field_refs": [
          "createOrder:response.201.body.order_id"
        ],
        "failure_paths": [
          {
            "reason": "Payment denied",
            "target_state": "payment_failed",
            "next_operation_id": "getOrder"
          }
        ]
      }
    ]
  }
}

このフローは、OpenAPI 内に注文のライフサイクルを直接定義します。

• created 状態から開始します
• 支払いが確認されると paid に遷移します
• 同期型とポーリング型の両方の遷移に対応します
• オペレーション間でデータを自動的に引き継ぎます
• AI によるオーケストレーション向けに、明示的な判断／根拠や失敗経路のメタデータを含めることができます

API 呼び出しを手動でオーケストレーションする代わりに、ワークフロー全体を API 仕様と併せて記述できます。

なぜこれが必要なのか

API の構築は簡単です。しかし、チームが実際に正しく使える複雑な複数ステップの APIを構築するのは困難です。

チームは、繰り返し次のような問題に直面します。

• 📄 手動で作成するドキュメントは壊れやすい – OpenAPI の仕様は静的で、実際のワークフローと同期していないことがよくあります
• 🤖 AI エージェントは幻覚を起こすことがあります – ワークフローが不明確または文書化されていない場合、LLM やコード生成エージェントが無効な呼び出しを生成することがあります
• 🤯 ワークフローは複雑です – 複数ステップの操作を人間や AI エージェントが追跡するのは困難です
• ⚠️ 無効な呼び出しが見過ごされます – ライフサイクルのルールが適用されないため、開発者がミスをします
• ⏱️ 統合に時間がかかります – SDK、Postman コレクション、ドキュメントを常に手動で更新する必要があります
• 🛡️ 本番環境でのエラーを防ぐのは困難です – 明示的なライフサイクルのルールがなければ、無効な操作が稼働中のシステムに到達し、停止や不整合を引き起こす可能性があります

x-openapi-flow は、こうした課題を解決するために存在します。ライフサイクルを明示し、遷移を自動で検証し、フローを考慮したドキュメントと SDK を生成することで、チームの作業を迅速化し、ミスを減らし、自信を持って統合をリリースできるようにします。

これで実現できること

OpenAPI の仕様を、API の動作に関する単一の信頼できる情報源にします。

• API のライフサイクルを Swagger UI と Redoc で直接可視化する
• CI パイプラインでフローと状態遷移を検証する
• OpenAPI の仕様からライフサイクル図を自動生成する
• API のワークフローを理解し、それを尊重する SDK を構築する
• ライフサイクルごとに整理された Postman および Insomnia コレクションをエクスポートする
• エージェントを活用した統合向けの AI 対応 API コントラクトを作成する
• 密度が高く、散文を含まないコーディングエージェント向けのフローコントラクト（export-llm-flows）をエクスポートする — または MCP ツールとして直接呼び出す — ことで、Claude Code のようなエージェントが人間向けドキュメントから再導出することなく、統合の実装に必要な正確な呼び出し順序、判断ルール、フィールド参照を把握できるようにします

クイックスタート（OpenAPI ファイルなし）

2 分で開始（オンラインプレイグラウンド）

ローカル環境をセットアップせずに試したい場合は、最小構成のランタイムガードデモをブラウザーで直接開いてください。

• StackBlitz: https://stackblitz.com/github/tiago-marques/x-openapi-flow/tree/main/example/runtime-guard/minimal-order
• Codespaces（リポジトリ）: https://github.com/tiago-marques/x-openapi-flow

開いたら、次を実行します。

npm install
npm run start

次に、別のターミナルで次を実行します。

curl -s -X POST http://localhost:3110/orders
curl -i -X POST http://localhost:3110/orders/<id>/ship

期待される結果: 409 INVALID_STATE_TRANSITION。

価値を確認する最速の方法（ガイド付きのひな形）:

npx x-openapi-flow quickstart
cd x-openapi-flow-quickstart
npm install
npm start

任意のランタイム:

npx x-openapi-flow quickstart --runtime fastify

次に、次を実行します。

curl -s -X POST http://localhost:3110/orders
curl -i -X POST http://localhost:3110/orders/<id>/ship

期待される結果: 409 INVALID_STATE_TRANSITION。

---

すでに OpenAPI ファイルがある場合は、サイドカーワークフローを使用してください。

プロジェクトでフローサポートを初期化します。

npx x-openapi-flow init
# optional: infer suggested transitions using naming heuristics
npx x-openapi-flow init --suggest-transitions

OpenAPI ファイルを再生成した後、フローを適用して検証します（任意）。

npx x-openapi-flow apply openapi.yaml --out openapi.flow.yaml

npx x-openapi-flow validate openapi.flow.yaml --profile strict --strict-quality

これにより、次のことができます。

• OpenAPI の仕様にフローメタデータを追加する
• ライフサイクルの整合性を検証する
• 無効な遷移を早期に検出する

💡 ヒント: API ワークフローの正確性を確保するため、CI で実行してください

大規模なフロー向けの簡潔な DSL

規模の大きな API では、リソースごとにフロールールを定義し（遷移やデフォルトを共有）、サイドカーファイル内の重複を減らすことができます。

参照: Sidecar Contract

GitHub Action（ワンステップの CI 検証）

公式の再利用可能なアクションを使用すると、1 つのステップで CI 内のライフサイクルルールを検証できます。

- name: Validate OpenAPI flow rules
  uses: tiago-marques/x-openapi-flow@v1
  with:
    openapi-file: openapi.flow.yaml
    profile: strict
    strict-quality: "true"

統合ガイド: GitHub-Actions-Integration.md

実際のライフサイクル例

x-openapi-flow で表現した、実際の決済ライフサイクルの例です。

CREATED -> AUTHORIZED -> CAPTURED -> REFUNDED

ライフサイクルのビジュアルグラフを生成します。

npx x-openapi-flow graph openapi.flow.yaml --format mermaid

生成された図：

graph TD
CREATED --> AUTHORIZED
AUTHORIZED --> CAPTURED
CAPTURED --> REFUNDED

この可視化により、API のワークフローが明確になり、共有しやすく、ドキュメントやデモにすぐ活用できます。

フローを考慮した SDK の生成

Stripe や Adyen のような業界をリードする企業のベストプラクティスに従い、API のライフサイクルと遷移ルールを尊重する TypeScript または Python の SDK を作成します。

• モデルごとのオーケストレーター：各リソースが、有効な遷移を強制するメソッドを公開します
• 連鎖可能な API 呼び出し：一連の処理を自然かつ安全に実行できます

npx x-openapi-flow generate-sdk openapi.flow.yaml --lang typescript --output ./sdk
npx x-openapi-flow generate-sdk openapi.flow.yaml --lang python --output ./sdk

使用例（TypeScript）：

const payment = await sdk.payments.create({ amount: 1000 });
await payment.authorize();
await payment.capture();

使用例（Python — 依存関係ゼロ、標準ライブラリの urllib を使用するクライアント。./sdk/src に生成されます）：

from src import FlowApiClient
from src.http_client import UrllibHttpClient

client = FlowApiClient(UrllibHttpClient("https://api.example.com"))
payment = client.payment.create({"body": {"amount": 1000}})
payment = payment.authorize()
payment = payment.capture()

この SDK は、有効な遷移経路に沿って開発者をガイドします。業界をリードする企業が採用するパターンに従い、安全で直感的なインテグレーションを実現します。

ランタイムでの強制（Express + Fastify + Hono）

CI での検証は重要ですが、本番環境の安全性を確保するにはリクエスト時の強制が必要です。

x-openapi-flow には、リクエスト処理中に無効な状態遷移をブロックできる、Node.js 用の公式ランタイムガードが含まれるようになりました。

• Express と Fastify で動作します
• operationId（利用可能な場合）、またはメソッドとルートを使ってオペレーションを解決します
• 独自の永続化コールバックを使って、現在のリソース状態を読み取ります
• 明示的な 409 エラーペイロードで無効な遷移をブロックします

API サーバーに直接インストールして使用します。

const {
  createExpressFlowGuard,
  createFastifyFlowGuard,
  createHonoFlowGuard,
} = require("x-openapi-flow/lib/runtime-guard");

Express の例：

const express = require("express");
const { createExpressFlowGuard } = require("x-openapi-flow/lib/runtime-guard");
const openapi = require("./openapi.flow.json");

const app = express();

app.use(
  createExpressFlowGuard({
    openapi,
    async getCurrentState({ resourceId }) {
      if (!resourceId) return null;
      return paymentStore.getState(resourceId); // your DB/service lookup
    },
    resolveResourceId: ({ params }) => params.id || null,
  })
);

Fastify の例：

const fastify = require("fastify")();
const { createFastifyFlowGuard } = require("x-openapi-flow/lib/runtime-guard");
const openapi = require("./openapi.flow.json");

fastify.addHook(
  "preHandler",
  createFastifyFlowGuard({
    openapi,
    async getCurrentState({ resourceId }) {
      if (!resourceId) return null;
      return paymentStore.getState(resourceId);
    },
    resolveResourceId: ({ params }) => params.id || null,
  })
);

Hono の例：

const { Hono } = require("hono");
const { createHonoFlowGuard } = require("x-openapi-flow/lib/runtime-guard");
const openapi = require("./openapi.flow.json");

const app = new Hono();

app.use(
  "*",
  createHonoFlowGuard({
    openapi,
    async getCurrentState({ resourceId }) {
      if (!resourceId) return null;
      return paymentStore.getState(resourceId);
    },
    resolveResourceId: ({ params }) => params.id || null,
  })
);

遷移がブロックされた場合のエラーペイロード：

{
  "error": {
    "code": "INVALID_STATE_TRANSITION",
    "message": "Blocked invalid transition for operation 'capturePayment'. Current state 'CREATED' cannot transition to this operation.",
    "operation_id": "capturePayment",
    "current_state": "CREATED",
    "allowed_from_states": ["AUTHORIZED"],
    "resource_id": "pay_123"
  }
}

詳細：ランタイムガード

組み込みの永続化アダプター

getCurrentState を一から独自に作成する必要はありません。x-openapi-flow には、すぐに使える 5 つのアダプターが含まれています。

const {
  MemoryAdapter,   // in-process Map — ideal for tests and single-instance dev
  FileAdapter,     // JSON file on disk — great for demos and local servers
  RedisAdapter,    // ioredis-backed — production-ready, requires: npm install ioredis
  GenericSQLAdapter, // any SQL DB (pg, mysql2, knex…) via query callback
  MongoAdapter,    // MongoDB Collection-backed, requires: npm install mongodb
} = require("x-openapi-flow/lib/runtime-guard");

// in-memory (testing / local)
const store = new MemoryAdapter();
app.use(createExpressFlowGuard({ openapi, ...store.forGuard() }));

// persist every transition to Redis
const Redis = require("ioredis");
const redisStore = new RedisAdapter({ client: new Redis(), prefix: "orders:" });
app.use(createExpressFlowGuard({ openapi, ...redisStore.forGuard() }));

// call setState after each successful request to keep the state in sync
app.post("/orders/:id/pay", async (req, res) => {
  await redisStore.setState({ resourceId: req.params.id, state: "paid" });
  res.json({ ok: true });
});

pg を使った GenericSQLAdapter の例：

const { Pool } = require("pg");
const pool = new Pool();
const sqlStore = new GenericSQLAdapter({
  query: (sql, params) => pool.query(sql, params).then(r => r.rows),
  dialect: "pg",
});
await sqlStore.ensureTable(); // CREATE TABLE IF NOT EXISTS xflow_state (…)
app.use(createExpressFlowGuard({ openapi, ...sqlStore.forGuard() }));

公式の mongodb ドライバーを使った MongoAdapter の例：

const { MongoClient } = require("mongodb");
const client = await new MongoClient(process.env.MONGO_URL).connect();
const mongoStore = new MongoAdapter({
  collection: client.db("orders").collection("xflow_state"),
});
app.use(createExpressFlowGuard({ openapi, ...mongoStore.forGuard() }));

すべてのアダプターは getCurrentState、setState、deleteState、およびガードオプションで期待される形式を返す便利なメソッド forGuard() を実装しています。

可観測性フック（メトリクス／監査）

onDecision を使ってランタイムの判定を計測し、Prometheus、ログ、トレースに送信できます。

const { Counter } = require("prom-client");
const { createExpressFlowGuard } = require("x-openapi-flow/lib/runtime-guard");

const flowDecisions = new Counter({
  name: "xflow_runtime_guard_decisions_total",
  help: "Runtime guard decisions by type and operation",
  labelNames: ["decision", "operation_id"],
});

app.use(
  createExpressFlowGuard({
    openapi,
    ...store.forGuard(),
    onDecision(event) {
      flowDecisions.inc({
        decision: event.decision,
        operation_id: event.operationId || "unknown",
      });
    },
  })
);

一般的な判定値は次のとおりです。

• allowed_transition
• allowed_idempotent_state
• allowed_initial_state
• denied_invalid_transition
• denied_missing_resource_id
• denied_unknown_operation
• skipped_unknown_operation

すぐに効果を確認したい場合は、公式の最小デモをお使いください。

• example/runtime-guard/minimal-order/README.md

5 分以内で実行できます。

cd example/runtime-guard/minimal-order
npm install
npm start

注文を作成し、支払い前に出荷を試します（409 INVALID_STATE_TRANSITION が返される必要があります）。

curl -s -X POST http://localhost:3110/orders
curl -i -X POST http://localhost:3110/orders/<id>/ship

HTTPie での同等の例：

http POST :3110/orders
http -v POST :3110/orders/<id>/ship

プログラムから利用できるステートマシンエンジン

CLI や OpenAPI の解析とは独立して、再利用可能な決定論的エンジンを使用できます。

const { createStateMachineEngine } = require("x-openapi-flow/lib/state-machine-engine");

const engine = createStateMachineEngine({
  transitions: [
    { from: "CREATED", action: "confirm", to: "CONFIRMED" },
    { from: "CONFIRMED", action: "ship", to: "SHIPPED" },
  ],
});

engine.canTransition("CREATED", "confirm");
engine.getNextState("CREATED", "confirm");
engine.validateFlow({ startState: "CREATED", actions: ["confirm", "ship"] });

詳細：ステートマシンエンジン

OpenAPI からエンジンへのアダプター

x-openapi-flow のメタデータを、純粋なエンジン定義に変換します。

const { createStateMachineAdapterModel } = require("x-openapi-flow/lib/openapi-state-machine-adapter");
const { createStateMachineEngine } = require("x-openapi-flow/lib/state-machine-engine");

const model = createStateMachineAdapterModel({ openapiPath: "./openapi.flow.yaml" });
const engine = createStateMachineEngine(model.definition);

詳細：OpenAPI ステートマシンアダプター

最もメリットが大きいユーザー

x-openapi-flow は、明確で強制可能な API ワークフローを求めるチームや組織に最適です。

• API ファーストの組織 – API の動作に関する単一の信頼できる情報源を維持します
• AI エージェントを開発するチーム – AI に適したコントラクトを提供し、API の正しい使用を徹底することで、エージェントが推測したりワークフローのルールに違反したりすることなく、正しい順序でエンドポイントを安全に呼び出せるようにします
• API プラットフォームチーム – エンドポイント全体で一貫したライフサイクルルールを確保します
• 複雑な API ワークフローを持つ企業 – 複数の手順を伴うプロセスでのエラーや曖昧さを減らします
• SDK チーム – 開発者をガイドする、フローを考慮した SDK を生成します

なぜ x-openapi-flow なのか？

x-openapi-flow が OpenAPI をどのように拡張し、API ワークフローを明示的で強制可能かつ実行可能にするのかをご覧ください。

機能	OpenAPI	x-openapi-flow
エンドポイントコントラクト	✅ あり	✅ あり（完全互換で拡張）
ライフサイクル状態	❌ なし	✅ あり – 各リソースの状態を定義
遷移の検証	❌ なし	✅ あり – 実行時より前に無効な呼び出しを検出
フロー図	❌ なし	✅ あり – ライフサイクルのグラフを視覚的に生成
使用方法のガイダンス（次に有効なアクション）	限定的／手動	✅ ライフサイクルメタデータに組み込み – 開発者と AI エージェントをガイド

OpenAPI Workflows（Arazzo）や AsyncAPI との違いは何ですか？

項目	x-openapi-flow	OpenAPI Workflows（Arazzo）	AsyncAPI
主な対象	リソースのライフサイクル状態と実行時の強制	複数ステップの API ワークフロー（オーケストレーションスクリプト）	イベント駆動型／非同期メッセージング API
ライフサイクル状態	✅ リソースごとに明示的な状態	❌ 状態モデルなし	❌ 状態モデルなし
実行時の強制	✅ Express/Fastify/Hono ミドルウェア（無効な遷移では 409）	❌ 仕様のみで、実行時のガードなし	❌ 仕様のみ
SDK 生成	✅ TypeScript、Python	❌ コード生成なし	限定的
Postman / Insomnia へのエクスポート	✅ アダプターを内蔵	❌ なし	❌ なし
AI エージェントのサポート	✅ MCP サイドカー + 機械処理向けフローコントラクト（export-llm-flows）	❌ なし	❌ なし
破壊的変更の検出	✅ diff --breaking-only --fail-on-breaking	❌ なし	❌ なし
CI 検証	✅ CLI + GitHub Action	❌ 公式 CLI なし	限定的
OpenAPI 互換性	✅ サイドカーで既存の仕様を拡張	独立した Arazzo 仕様	独立した AsyncAPI 仕様

要約：ドキュメントの範囲を超えて、実行時の安全性、SDK 生成、AI 対応コントラクトを実現する強制可能で状態を持つ API ライフサイクルが必要な場合は、x-openapi-flow を使用してください。複数ステップにわたる HTTP の一連の処理をスクリプト化するには Arazzo を使用してください。イベント／メッセージ駆動型システムをドキュメント化するには AsyncAPI を使用してください。

統合デモ

x-openapi-flow が一般的な API ツールとどのように統合し、ドキュメントやテストでライフサイクルとフローを明示できるかをご覧ください。

Swagger UI – ドキュメントでフローを可視化

cd example/swagger-ui
npm install
npm run apply
npm start

ライフサイクルパネルに有効な状態と遷移が表示されます

操作ごとの遷移の詳細ビュー

Redoc – フローを考慮したドキュメント

cd example/redoc
npm install
npm run apply
npm run generate

自動生成されるライフサイクル図により、ドキュメントが明確で一貫したものになります

Postman – 整理された API コレクション

cd example/postman
npm install
npm run apply
npm run generate

コレクションはライフサイクルの順序を反映し、統合エラーを減らします

Insomnia – 整理された API コレクション

cd example/insomnia
npm install
npm run apply
npm run generate

リクエストはライフサイクルの遷移に従って、あらかじめ整理されています

CLI リファレンス – よく使うコマンド

コマンドラインから x-openapi-flow を使用して、API ワークフローの管理、検証、可視化、SDK／ドキュメントの生成を行います。

一般

npx x-openapi-flow help [command]         # show help for a specific command

npx x-openapi-flow --help                 # general help

npx x-openapi-flow version                # show version

npx x-openapi-flow doctor [--config path] # check setup and config

npx x-openapi-flow completion [bash|zsh]  # enable shell autocompletion

npx x-openapi-flow quickstart [--dir path] [--runtime express|fastify] [--force] # scaffold runnable onboarding project

ワークフロー管理

# initialize flow support
npx x-openapi-flow init [--flows path] [--force] [--dry-run]   

# apply flows to OpenAPI
npx x-openapi-flow apply [openapi-file] [--flows path] [--out path]  

# validate transitions
npx x-openapi-flow validate <openapi-file> [--profile core|relaxed|strict] [--strict-quality] [--semantic]  

# preview sidecar changes
npx x-openapi-flow diff [openapi-file] [--format pretty|json]

# detect breaking flow changes (use in CI to fail PRs)
npx x-openapi-flow diff [openapi-file] --breaking-only --fail-on-breaking

# generate a Markdown migration guide for breaking flow changes
npx x-openapi-flow migrate [openapi-file] [--flows path] [--format markdown|json] [--out path]

可視化とドキュメント

# generate lifecycle diagrams
npx x-openapi-flow graph [openapi-file] [--format mermaid|json]   

# generate Redoc docs
npx x-openapi-flow generate-redoc [openapi-file] [--output path]   

# export human-readable flow docs (Mermaid diagrams + prose)
npx x-openapi-flow export-doc-flows [openapi-file] [--output path] [--format markdown|json]  

# export a machine-oriented flow contract for coding agents (not for humans)
npx x-openapi-flow export-llm-flows [openapi-file] [--output path] [--format yaml|json]

SDK の生成

# generate flow-aware SDK (typescript or python)
npx x-openapi-flow generate-sdk [openapi-file] --lang typescript|python [--output path] 

テストの生成

# generate executable flow tests (happy path + invalid transitions)
npx x-openapi-flow generate-flow-tests [openapi-file] [--format jest|vitest|postman] [--output path]

# postman/newman-oriented collection with flow scripts
npx x-openapi-flow generate-flow-tests [openapi-file] --format postman [--output path] [--with-scripts]

詳細はこちらをご覧ください。

• CLI リファレンス
• README

NestJS との統合

専用パッケージ：x-openapi-flow-nestjs-kit

npm install x-openapi-flow x-openapi-flow-nestjs-kit

次に、x-openapi-flow-nestjs-kit からインポートします。

このパッケージは公式のランタイムガードヘルパーをラップし、NestJS を優先した API を提供します。

このパッケージのリリース自動化では、nestjs-v<version> 形式の専用タグ（例：nestjs-v0.1.1）を使用するため、x-openapi-flow のタグと競合しません。

オプション A：ミドルウェア（そのまま使用可能）

// flow-guard.middleware.ts
import { Injectable, NestMiddleware } from "@nestjs/common";
import { createFlowMiddleware, MemoryAdapter } from "x-openapi-flow-nestjs-kit";
import openapi from "./openapi.flow.json";

const store = new MemoryAdapter(); // swap for RedisAdapter or GenericSQLAdapter in production
const guard = createFlowMiddleware({ openapi, ...store.forGuard() });

@Injectable()
export class FlowGuardMiddleware implements NestMiddleware {
  use(req: any, res: any, next: () => void) {
    guard.use(req, res, next);
  }
}

// app.module.ts — apply to specific routes
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(FlowGuardMiddleware).forRoutes("orders");
  }
}

オプション B：CanActivate ガード

// flow.guard.ts
import { CanActivate, ExecutionContext, Injectable } from "@nestjs/common";
import { createFlowGuard, MemoryAdapter } from "x-openapi-flow-nestjs-kit";
import openapi from "./openapi.flow.json";

const store = new MemoryAdapter();
const flowGuard = createFlowGuard({ openapi, ...store.forGuard() });

@Injectable()
export class FlowGuard implements CanActivate {
  canActivate(context: ExecutionContext) {
    return flowGuard.canActivate(context);
  }
}

状態を変更するリクエストが成功するたびに、store.setState を呼び出してリソースを次の状態へ進めます。

@Post(":id/pay")
async pay(@Param("id") id: string) {
  // … business logic …
  await store.setState({ resourceId: id, state: "paid" });
  return { ok: true };
}

ドキュメントとガイド

詳細なガイド、例、統合手順を確認して、x-openapi-flowを最大限に活用しましょう。

• 導入ガイド – docs/wiki/getting-started/Adoption-Playbook.md
  x-openapi-flowをAPIワークフローに効率よく導入する方法を学べます。

• トラブルシューティング – docs/wiki/reference/Troubleshooting.md
  よくある問題や検証エラーへの簡単な解決策を確認できます。

• 実例 – docs/wiki/engineering/Real-Examples.md
  ライフサイクルメタデータで拡張された実際のOpenAPI仕様を確認できます。

• 統合：

  • GitHub Actions – docs/wiki/integrations/GitHub-Actions-Integration.md
    再利用可能なワークフローのステップ1つで、CI内のフロールールを検証します。
  • Swagger UI – docs/wiki/integrations/Swagger-UI-Integration.md
    Swagger UIでフロー対応パネルを確認できます。
  • Redoc – docs/wiki/integrations/Redoc-Integration.md
    Redocのドキュメントでライフサイクル図を生成します。
  • Postman – docs/wiki/integrations/Postman-Integration.md
    有効な遷移に従ってコレクションを整理します。
  • Insomnia – docs/wiki/integrations/Insomnia-Integration.md
    ライフサイクルフローに従ってリクエストを事前設定します。

コミュニティと実績

• 事例を共有する – docs/wiki/community/Case-Study-Template.md
• ディスカッションやアイデアを投稿する – GitHub Issuesを使って、導入の障壁、指標、統合事例を共有します : .github/ISSUE_TEMPLATE/case-study.ymlと.github/ISSUE_TEMPLATE/adoption-blocker.ymlの構造化フォームを使用してください
• 指標で効果を実証する – 導入前後のdenied_invalid_transition、オンボーディングのリードタイム、CIでの検出率を追跡します

ロードマップ

x-openapi-flowは、複数のプラットフォームとSDKをサポートするため、積極的に拡張を進めています。進捗をご確認ください。

• 🗂 ロードマップの概要 – #2
  予定されている機能と大まかな目標を確認できます。

• 🐍 Python SDK MVP – #3
  Python開発者がフロー対応SDKを利用できるようにします。

• 🏎 Go SDK MVP – #4
  Goプロジェクトでライフサイクル対応SDKを利用できるようにします。

• ☕ Kotlin SDK MVP – #5
  AndroidおよびJVMの開発者がフロー対応SDKを利用できるようにします。

変更履歴

x-openapi-flow の更新と改善を確認できます。

• 最新バージョン（v1.7.0） – CHANGELOG.md#170---2026-04-02
  現在のリリースに含まれる内容をご確認ください。

• バージョン履歴 – CHANGELOG.md
  バージョン履歴全体と過去の更新内容をご確認ください。

• リリースノート – GitHub Release v1.7.0
  新機能や修正を含む、最新リリースの詳細なノートをご確認ください。

ドキュメントの言語方針

世界中の開発者コミュニティにとって明確で利用しやすいものにするため、プロジェクトのドキュメントはすべて英語で記述してください。これにより、コントリビューター、ユーザー、AI エージェントが一貫して x-openapi-flow を理解し、利用できるようになります。