テーマ
OpenAPI仕様書
OpenAPI仕様書を開き、エンドポイントのリクエスト形式を確認する手順を説明します。
対象読者
開発者
前提
- サイドメニューに「開発者ツール」が表示される権限があること
- 更新系のAPIを試す場合は、実データに影響しない検証用テナントを用意していること
知っておくこと
OpenAPI仕様書はacomo APIの 正式な契約 です。パス、HTTPメソッド、リクエストボディ、レスポンス型、認証要件が定義されています。
製品内では次の2か所から同じ仕様に到達できます。
| 入口 | 説明 |
|---|---|
| サイドメニュー「OpenAPI仕様書」 | /api — Swagger UI |
| 「API」画面の「仕様を見る」 | /api#{タグ}/{operationId} へディープリンク |
「API」画面(/development/apis)の各行は、Operation IDとOpenAPI上の操作を対応付けています。
仕様を読む手順
- 「API」で対象の Operation ID(例:
listWorkflowModels)を探します。 - 行メニュー「仕様を見る」を開くか、「OpenAPI仕様書」でタグ(例:
Model)配下を開きます。 - Authorize で
Authorization(セッションJWTまたはアクセストークン)とTenant(テナントID)を設定します。 - パラメータとレスポンススキーマを確認します。動作確認に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を正として確認してください。