Keep the API reference tied to real operations

Declared resource operations flow into an API document and an endpoint reference with matching rows

Keep the API reference tied to real operations

The API contract is derived from the application’s resolved resource operations and authored specifications. That connects endpoint descriptions and request shapes to the mechanisms integrations actually call.

Example — Expose a new business action

A declared action with its inputs and access policy appears in the projected API contract. The reference explains that action from its specification instead of inventing a second handwritten endpoint definition.

For engineers

The application’s documentation configuration supplies its supported API version, resource selection and server addresses. A selected Wonder CRM configuration fragment illustrates those inputs:

export default defineTechnicalDocConfig({
  supportedApiVersion: '1.0.0',
  publicMarketingTitle: 'Wonder CRM — Technical Documentation',
  apiDocResources: 'all',
  apiServers: [
    { url: 'http://localhost:4251', description: 'Local development' },
  ],
  // Existing category and overview settings remain here.
});

defineTechnicalDocConfig is a public root export. The server URL is an origin: operation paths already include the API mount. 'all' includes the eligible core resources in addition to application resources, subject to the resolved feature and publication inputs.

Carry the operation’s meaning into its reference

Wonder CRM’s company specification authors this CREATE description. This selected operation entry uses its existing Op and HTTP-status enums:

[Op.CREATE]: {
  purpose: 'Record a new company.',
  outcome: 'The new company exists, with its identifier and the time it was created.',
  responseStatuses: [{ code: HttpResponseStatusCode.CREATED_201, meaning: 'The record was created and returned.' }],
  errorScenarios: [
    { code: HttpResponseStatusCode.BAD_REQUEST_400, when: 'The payload fails validation.', errorCode: 'VALIDATION_FAILED' },
  ],
  idempotent: false,
  // The specification also supplies request/response examples.
},

The company resource configuration enables CREATE with its shared schema and resolved access policy. Its specification supplies meaning; neither the specification alone nor this excerpt creates an endpoint.

The inspected generated API artifact carries that meaning into the ordinary route:

/api/v1/organizations/{organizationId}/company:
  post:
    operationId: createCompany
    summary: Create company
    description: |-
      Record a new company.

      The new company exists, with its identifier and the time it was created.

This is a selected snapshot of Wonder CRM’s generated api.json, expressed as YAML for reading. The full operation also carries its parameters, request body, security and responses. The snapshot demonstrates the declaration-to-reference join; it does not report an endpoint call made during this website work.

Project, reconcile, then publish

Introspection produces JSON-safe operation projections and the inventory they came from. The service reconciles that inventory against the projections before generating OpenAPI. Specifications supply semantic descriptions; resolved access documents supply operation security. Generation and publication are separate companion operations.

Inspect the generated documents and the browser reference after changing a resource contract. Conservation checks establish that eligible operations were not lost in projection; they do not execute an endpoint or prove the target server is deployed at the configured address. Custom operation documentation still needs meaningful authored input and result descriptions.

Keep the API reference tied to real operations