dify/packages/contracts

Contracts

API OpenAPI Readiness

Snapshot generated from packages/contracts/generated/api/readiness.json after running pnpm -C packages/contracts gen-api-contract-from-openapi.

Are we OpenAPI ready? No. Current generated API contracts are 16.7% ready.

Surface	Ready	Not ready	Total	Ready %
console	96	474	570	16.8%
service	16	72	88	18.2%
web	5	36	41	12.2%
total	117	582	699	16.7%

Readiness here means the generated contract operation is not marked with:

Generated contract types may be inaccurate because backend OpenAPI annotations are incomplete. Do not migrate callers until the generated contract is accurate.

Operations marked with that warning should not be migrated to blindly. Prefer fixing backend OpenAPI annotations first so the generated contract has accurate request and response types, then migrate callers endpoint by endpoint.

The current heuristic marks an operation as not ready when a request body or success response that should have a body contains a loose object type, or when an operation has no documented 2xx response. 204, 205, and 304 responses are treated as bodyless when the request type is otherwise accurate.

How to Improve Readiness

Improve the ready percentage by fixing the backend annotations that produce loose generated types, then regenerating the contracts.

• Add accurate request body schemas for endpoints that currently generate loose object types.
• Add accurate 2xx response schemas for endpoints that return JSON payloads.
• Use 204 responses for endpoints that intentionally return no body.
• Avoid untyped dictionaries, raw objects, or additionalProperties: true responses unless the API really returns an arbitrary object.
• Regenerate with pnpm -C packages/contracts gen-api-contract and use this README to verify the updated percentage.

Do not remove the generated warning just to increase the number. The warning should disappear because the backend OpenAPI output became accurate enough for callers to migrate safely.