Export

accorudo export walks a contract bundle and emits a valid OpenAPI 3.x document. Use it to publish specs, feed documentation tools, or diff against a backend's canonical file.

Basic usage

accorudo export ./contracts/main --out ./openapi/main.yaml

JSON output:

accorudo export ./contracts/main --out ./openapi/main.json

What gets exported

Each route alias in api.ts becomes an OpenAPI path item:

Tags come from the route file name (routes/widget.ts → tag widget), or from @openapi.tag on the route alias. See OpenAPI annotations.

Schemas in models/ become OpenAPI components.schemas when marked with @openapi.component. References to component types emit $ref by default; use @openapi.inline to embed a schema instead.

Preview output

accorudo export ./contracts/main --dry-run

Prints the full spec to stdout. Pipe to a diff tool:

accorudo export ./contracts/main --dry-run | diff openapi/main.yaml -

Config-driven export

With accorudo.config.ts:

accorudo sync main --reverse

Exports contracts/main to the openapi path defined for that bundle.

Limitations

Export reflects what Accorudo types express. It cannot recover:

• Server URLs beyond a placeholder servers entry (set via config)
• Security schemes not represented in route types
• OpenAPI-only metadata without annotations (deprecated, examples, externalDocs)

Add missing metadata with OpenAPI annotations, or maintain a base spec and merge. For CI validation, export and diff against the backend spec to catch drift in paths, methods, and core schemas.

Round-trip

Import → hand-edit → export should produce a spec equivalent in paths and schemas. Naming and operationId values may differ. Use diff tools on normalized output, not byte-identical files.

accorudo import  ./openapi/main.yaml --out ./contracts/main
# … hand-edit contracts …
accorudo export  ./contracts/main --out ./openapi/generated.yaml
diff openapi/main.yaml openapi/generated.yaml