kata-api-design-doc

REST API documentation is generated by transforming feature directives into endpoint designs, payloads, headers, pagination, and error rules. This produces a structured Markdown file saved under docs/{context}/oas/.

Designing REST endpoints with consistent idempotency and error handling requires aligning statuses, payload shapes, and headers with platform codexes. This ensures standardized auth behavior and idempotency-key rules across all operations.

Markdown documentation complements your existing OpenAPI file by providing a human-readable specification alongside the canonical artifact. It includes endpoint tables, global headers, known errors, and examples for bounded contexts.

Structuring API payloads, pagination, and sorting rules involves converting feature descriptions into concrete resources and operations. The tool validates endpoint completeness and outputs standardized entity structures aligned with REST codexes.

This approach works for designing both public and private APIs within platform bounded contexts. It transforms feature directives into endpoint designs and generates human-readable Markdown documentation alongside the canonical OpenAPI file.