OpenAPI → Markdown

Turn OpenAPI specs into readable docs.

Paste OpenAPI 3 / Swagger (YAML or JSON). Get clean, MDX-ready markdown with endpoint tables, request bodies, response codes, and schemas.

YAML & JSONGroups by tagMDX-friendly

OpenAPI spec

Paste your OpenAPI 3.x or Swagger 2.x spec as YAML or JSON.

Output options

3
Endpoints
1
Tags
1
Schemas
1.0.0
Version
Documentation completeness35/100
  • API description
  • Summaries · 3/3
  • Descriptions · 0/3
  • Parameter docs · 1/2
  • Has an example
  • Documents auth
Petstore — Markdownmarkdown
# Petstore

**Version:** `1.0.0`

A simple petstore API for demo purposes.

## Base URLs

- `https://api.petstore.example` — Production

## Endpoints

### List all pets

```http
GET /pets
```

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | `integer (int32)` | no | Max number of pets to return. |

#### Responses

| Status | Description | Content type |
| --- | --- | --- |
| `200` | Paged list of pets | application/json |

### Create a pet

```http
POST /pets
```

#### Request body

**application/json**

```json
{
  "$ref": "#/components/schemas/Pet"
}
```

Example:

```json
null
```

#### Responses

| Status | Description | Content type |
| --- | --- | --- |
| `201` | Created | — |

### Get a pet by ID

```http
GET /pets/{petId}
```

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `petId` | path | `string` | yes | — |

#### Responses

| Status | Description | Content type |
| --- | --- | --- |
| `200` | A pet | application/json |
| `404` | Not found | — |

## Data models

### Pet

```json
{
  "type": "object",
  "required": [
    "id",
    "name"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "tag": {
      "type": "string"
    }
  }
}
```
MDX-ready output
The markdown uses ATX headings, fenced code, and pipe tables — drop it straight into app/docs/api/page.mdx or any docs platform that speaks markdown.
Dokly

Want auto-synced API docs?

Dokly keeps your API reference in sync with your OpenAPI spec on every commit — no manual conversion, no drift.

Try Dokly free →

Why convert OpenAPI to Markdown?

OpenAPI (formerly Swagger) is the standard for describing REST APIs in a machine-readable way. But humans don't read raw YAML — they read narrative documentation with examples, prose, and context. Converting to markdown bridges that gap.

What this tool does

  • Accepts OpenAPI 3.x or Swagger 2.x in YAML or JSON.
  • Generates one section per endpoint with an HTTP method block, description, and parameter / response tables.
  • Groups operations by tag (when present) so the output is navigable — e.g., Pets, Users, Auth.
  • Outputs everything in MDX-friendly markdown — no HTML, no inline JSX, just clean ATX headings, fenced code, and pipe tables.

Common workflows

  • Static API reference: commit the generated markdown into your docs repo for versioned history.
  • Migrating off Swagger UI: replace the interactive playground with narrative docs that read well and rank in search.
  • AI-friendly docs: markdown is what LLMs ingest best — making your API more discoverable to ChatGPT, Claude, and Cursor.

Frequently asked questions

What's the difference between OpenAPI and Swagger?
Swagger was the original name for both the spec format and the tooling around it. In 2016 the spec was donated to the Linux Foundation and renamed OpenAPI — version 2.0 is still commonly called "Swagger", while 3.0+ is called OpenAPI. This tool reads both: a `swagger: "2.0"` field or an `openapi: "3.x"` field.
Can I convert a Swagger 2.0 spec, not just OpenAPI 3?
Yes. The parser reads `paths`, `parameters`, `responses`, and `definitions`/`components.schemas` the same way regardless of which version header is present — Swagger 2.0's shape is close enough to OpenAPI 3 for the fields this tool uses. If a 2.0-specific field like `host` + `basePath` instead of `servers` trips up a conversion, the output still renders; it just won't list a base URL.
Why convert an OpenAPI spec to Markdown instead of using Swagger UI?
Swagger UI is an interactive playground — great for trying a request, bad for narrative docs that explain why an endpoint exists or how fields relate to each other. Markdown reads as documentation, lives in version control next to the spec, and renders on any platform that speaks Markdown (a docs site, a GitHub wiki, an internal knowledge base) without hosting a separate app.
Does this tool send my spec anywhere?
No. Parsing and conversion both happen in your browser — the spec never leaves your machine. That's also why the completeness checker below works on specs with private endpoint names or internal hostnames: there's no server call to worry about.
What does the documentation completeness score check?
Six things a reader actually needs, not just what's technically valid YAML: an API-level description, whether most endpoints have a summary, whether at least half have a longer description, whether documented parameters explain what they're for, whether any endpoint shows a real example value, and whether auth is declared via a security scheme. A spec can be perfectly valid OpenAPI and still score low here — validity and documentation quality are different things.
My spec has no parameters on some endpoints — does that hurt the score?
No. The parameter-description check only looks at endpoints that declare parameters; a `GET /health` with no inputs isn't penalized for having nothing to describe. The score focuses on what's actually missing, not on things that don't apply.
Why does the converter group endpoints by tag?
OpenAPI's `tags` field is how spec authors already organize related endpoints — e.g. all `/pets/*` routes tagged `Pets`. Reusing that grouping as Markdown `##` headings means the converted docs follow a structure the API author already chose, instead of a flat alphabetical list of paths.
Can I use the converted Markdown directly in Dokly or another MDX-based docs tool?
Yes — the output is plain ATX headings, fenced code blocks, and pipe tables, with no HTML and no inline JSX, so it drops into any Markdown or MDX file without modification. Dokly specifically can keep this reference in sync automatically on every commit instead of needing a re-paste each time the spec changes.