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

Upload file

openapi: 3.0.3
info:
  title: Petstore
  version: 1.0.0
  description: A simple petstore API for demo purposes.
servers:
  - url: https://api.petstore.example
    description: Production
paths:
  /pets:
    get:
      tags: [Pets]
      summary: List all pets
      operationId: listPets
      parameters:
        - name: limit
          in: query
          required: false
          schema: { type: integer, format: int32 }
          description: Max number of pets to return.
      responses:
        '200':
          description: Paged list of pets
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Pet' }
    post:
      tags: [Pets]
      summary: Create a pet
      operationId: createPet
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Pet' }
      responses:
        '201': { description: Created }
  /pets/{petId}:
    get:
      tags: [Pets]
      summary: Get a pet by ID
      parameters:
        - name: petId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: A pet
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Pet' }
        '404': { description: Not found }
components:
  schemas:
    Pet:
      type: object
      required: [id, name]
      properties:
        id: { type: string }
        name: { type: string }
        tag:  { type: string }

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

Output options

Group endpoints by tagUse the first OpenAPI tag as an H2 group heading.Include authentication blockRender `security` requirements per endpoint.Include data models sectionAppend a `## Data models` block with all schemas.

Endpoints

Tags

Schemas

1.0.0

Version

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.

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.