OpenAPI仕様書

OpenAPI仕様書を開き、エンドポイントのリクエスト形式を確認する手順を説明します。

対象読者

開発者

前提

• サイドメニューに「開発者ツール」が表示される権限があること
• 更新系の API を試す場合は、実データに影響しない検証用テナントを用意していること

知っておくこと

OpenAPI仕様書は acomo API の 正式な契約 です。パス、HTTP メソッド、リクエストボディ、レスポンス型、認証要件が定義されています。

製品内では次の 2 か所から同じ仕様に到達できます。

入口	説明
サイドメニュー「OpenAPI仕様書」	/api — Swagger UI
「API」画面の「仕様を見る」	/api#{タグ}/{operationId} へディープリンク

「API」画面（/development/apis）の各行は、Operation ID と OpenAPI 上の操作を対応付けています。

仕様を読む手順

1. 「API」で対象の Operation ID（例: listWorkflowModels）を探します。
2. 行メニュー「仕様を見る」を開くか、「OpenAPI仕様書」でタグ（例: Model）配下を開きます。
3. Authorize で Authorization（Bearer セッションまたはアクセストークン）と Tenant（認証テナント ID）を設定します。
4. パラメータとレスポンススキーマを確認します。動作確認に Try it out を使う場合は、次の注意を守ります。

Try it out は業務データを変更できる

サインイン済みのテナントに対して、そのセッションの権限で API が実行されます。

• ステージングや検証用テナント で試してください。本番テナントでは GET などの参照系 に限定してください。
• POST、PUT、DELETE は、プロセスの開始・提出・承認やデータの更新・削除など、実データを変更します。
• 本番で誤ってプロセスを作成した場合は、テナント管理者またはワークフロー管理者に連絡し、プロセスの扱いを確認してください。
• タイムアウトや通信切断が発生した場合は、現在のデータと操作履歴を確認してから再実行してください。

TypeScript 向けには、OpenAPI から生成された @acomo/client パッケージを利用できます。組織のビルドパイプラインでクライアントを再生成する運用が一般的です。

OpenAPI に表示される認証方式

スキーム	ヘッダー	用途
Authorization	Authorization: Bearer <token>	セッション JWT またはアクセストークン
Tenant	x-tenant-id: <authTenantId>	操作対象の認証テナント

実行結果を確認する

• Operation ID で「API」と OpenAPI の節が一致すること
• 403 時はレスポンス本文と、必要なシステム実行ポリシー列を照合すること

うまくいかないとき

• 仕様が見つからない場合は、「API」で Operation ID を再検索してください。
• Try it out で 401 が返る場合は、API 認証のヘッダー設定を確認してください。
• 本番で誤って Engine の POST を実行した場合は、作成されたプロセスを管理者に報告してください。
• 型と実装が一致しない場合は、利用中の acomo バージョンの OpenAPI を正として確認してください。

次に読む

• 認可の仕組みとAPI上の挙動