Home Getting Started Human Spec LLM Spec

Convert from OpenAPI

Already have an OpenAPI or Swagger specification? Transform it into MAPI format to make it LLM-friendly while keeping compatibility with existing tooling.

Choose your method

You can convert OpenAPI to MAPI using an LLM (recommended) or manually. The LLM approach is faster and handles the mechanical translation, letting you focus on improving Intentions and Logic Constraints.

LLM-Assisted

Recommended — fast and accurate

Manual

Full control over the output

LLM-assisted conversion

Give an LLM your OpenAPI spec along with the conversion reference card. It handles the field mapping, type conversion, and structural transformation automatically.

OpenAPI to MAPI Reference Card

Raw markdown for LLM consumption — field mappings and conversion rules
Fetch this page: https://markdownapi.org/specs/OPENAPI-TO-MAPI.md

Or paste this prompt directly into your LLM chat

Just attach both files and ask:

You
JS
Convert this OpenAPI spec to MAPI format. Write meaningful Intentions that explain when and why to use each capability.
OPENAPI-TO-MAPI.md
openapi.yaml
Claude
C
I'll convert your OpenAPI spec to MAPI format, focusing on clear Intentions...

# Pet Store API

[Generates complete MAPI spec with Intentions, TypeScript schemas, Logic Constraints...]
Better Intentions

OpenAPI descriptions are often sparse. After conversion, ask the LLM to "expand the Intentions with more context about when to use each capability and any important tradeoffs." This is where MAPI adds the most value.

Manual conversion

If you prefer full control, convert manually using the reference card as your guide. The key mappings:

  • info.title → H1 title
  • info.version, servers[0].url, securityDefinitions → Document ~~~meta block
  • Each paths.{path}.{method} → A ## Capability: section
  • operationId → id: in capability meta
  • summary + description → Expand into ### Intention
  • JSON Schema → TypeScript interfaces (see reference card for type mapping)
  • responses.200 → ~~~response 200 block
  • Standard error codes → > Errors: standard (400, 401, ...)

OpenAPI to MAPI Reference Card

Complete field mapping tables and conversion templates
Fetch this page: https://markdownapi.org/specs/OPENAPI-TO-MAPI.md

Or paste this prompt directly into your LLM chat

What you gain

Converting from OpenAPI to MAPI isn't just reformatting. You're adding:

  • Intentions — OpenAPI has summary and description, but they're often terse. MAPI Intentions explain the "why."
  • Logic Constraints — Business rules buried in OpenAPI descriptions become explicit, scannable bullet points.
  • Readability — Markdown with TypeScript is more approachable than JSON Schema.
  • LLM compatibility — MAPI is designed for AI consumption; OpenAPI is designed for code generators.

Keep both formats

You don't have to choose. Many teams maintain MAPI as the source of truth (for humans and LLMs) and generate OpenAPI from it (for tooling). See Export to OpenAPI.

Next steps

Have an LLM write a spec Validate your spec Export back to OpenAPI