Home Getting Started Human Spec LLM Spec

Export to OpenAPI

Need OpenAPI for legacy tooling, code generators, or API gateways? Generate OpenAPI specs from your MAPI documents while preserving MAPI-specific information.

Why export?

MAPI is great for humans and LLMs, but the ecosystem is built on OpenAPI. You might need OpenAPI for:

  • Code generation — Client SDKs, server stubs, types
  • API gateways — Kong, AWS API Gateway, Apigee
  • Documentation tools — Swagger UI, Redoc, Stoplight
  • Testing tools — Postman, Insomnia, Dredd
  • Validation — Request/response validation middleware

The solution: maintain MAPI as your source of truth, generate OpenAPI when tools demand it.

LLM-assisted export

Attach your MAPI spec and the export reference card:

MAPI to OpenAPI Reference Card

Raw markdown for LLM consumption — export mappings and extension patterns
Fetch this page: https://markdownapi.org/specs/MAPI-TO-OPENAPI.md

Or paste this prompt directly into your LLM chat

You
JS
Generate an OpenAPI 3.1 spec from this MAPI document. Preserve Intentions and Logic Constraints in x-mapi-* extensions.
MAPI-TO-OPENAPI.md
pet-store.mapi.md
Claude
C
I'll generate an OpenAPI 3.1 specification from your MAPI document...

openapi: "3.1.0"

[Generates full OpenAPI with x-mapi-intention and x-mapi-constraints extensions...]

What gets preserved

OpenAPI can't express everything MAPI has. The reference card uses extensions to preserve:

  • Intentions → x-mapi-intention (beyond the summary)
  • Logic Constraints → x-mapi-constraints
  • SSE events → x-mapi-events
  • Capability grouping → x-mapi-capability

This means you can convert MAPI → OpenAPI → MAPI without losing information.

WebSocket limitation

OpenAPI 3.x doesn't support WebSocket. WebSocket capabilities can be preserved in x-mapi-websocket extensions, but won't be usable by standard OpenAPI tools. Consider generating a separate AsyncAPI file for event-driven endpoints.

The dual-format workflow

Many teams use this pattern:

  1. Author in MAPI — Human-readable, LLM-friendly source of truth
  2. Export to OpenAPI — On-demand, for tooling that needs it
  3. Generate artifacts — SDKs, docs, gateway configs from OpenAPI
  4. Keep MAPI updated — Changes go to MAPI first, then re-export

This gives you the best of both worlds: MAPI's readability and OpenAPI's ecosystem compatibility.

Next steps

Write a MAPI spec Import from OpenAPI Validate your spec