OpenAPI Generation

Documentation status: architecture — see Maturity and evidence.

OpenAPI is a documentation projection of published HTTP services. The generated document must reflect the public contract that is actually exposed and must not leak private implementation types or names.

Source of truth

The recommended chain is:

published model capability
    -> HTTP service contract
    -> route/schema metadata
    -> OpenAPI document

The OpenAPI document is therefore derived from the publication contract; it must not become the primary source of the business model.

Requirements

Reliable generation should preserve:

• public names;
• parameter and return types;
• nullability;
• arrays and published objects;
• documentable errors;
• security requirements;
• contract version;
• async/job semantics where relevant.

A signature that cannot be projected should produce an explicit diagnostic rather than an approximate OpenAPI description.