Which spec versions are supported?

OpenAPI 3.0 and 3.1, plus Swagger 2.0. Both JSON and YAML input work — the format is detected automatically. Swagger 2.0 fields like host , basePath , schemes , definitions , and securityDefinitions map to the same output sections as their OpenAPI 3 equivalents.

Does it resolve $ref pointers?

Local refs ( #/components/schemas/Pet , #/definitions/User ) resolve to real field tables, and schema names link to the schema reference section. Circular refs are detected and labelled instead of looping forever. Refs to external files or URLs cannot be fetched client-side, so they appear as a labelled placeholder — bundle your spec first if you need them inlined.

Is my spec uploaded anywhere?

No. Parsing and Markdown generation run entirely in your browser. Nothing is sent to a server, which makes this safe for internal or unreleased APIs.

Can I paste the output into Confluence or Jira?

Yes. Generate the Markdown here, then run it through the Markdown to Confluence or Markdown to Jira converter to get storage format or wiki markup.

Why are some description cells showing a dash?

A dash means that field has no description in the spec. Markdown table cells cannot be empty without breaking alignment, so blanks are filled with an em dash. Add description entries to your spec to fill them in.

What happens to operations without tags?

They are collected under a single "Endpoints" heading. Turn off "Group by tag" to put every operation under that one heading regardless of tags.

OpenAPI to Markdown

Paste an openapi.yaml or swagger.json file and get a Markdown API reference you can drop into a README, a docs site, a Confluence page, or a pull request. The converter groups endpoints by tag, merges path-level parameters into each operation, resolves local $ref pointers into field tables, and handles both OpenAPI 3.x (servers, components) and Swagger 2.0 (host, basePath, definitions). Circular references stop safely instead of looping. Everything runs client-side, so internal specs never leave your machine.

Table of contentsGroup by tagSchema referenceExamples

Upload spec

OpenAPI 3.x or Swagger 2.0 spec (JSON or YAML)

openapi: 3.0.3
info:
  title: Orders API
  version: 1.4.0
  description: Create and track customer orders.
servers:
  - url: https://api.example.com/v1
    description: Production
tags:
  - name: orders
    description: Order lifecycle endpoints
paths:
  /orders:
    get:
      tags: [orders]
      summary: List orders
      operationId: listOrders
      parameters:
        - name: status
          in: query
          description: Filter by order status.
          schema:
            type: string
            enum: [pending, shipped, cancelled]
        - name: limit
          in: query
          schema: { type: integer, format: int32, default: 25 }
      responses:
        '200':
          description: A page of orders.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
        '401':
          description: Missing or invalid token.
    post:
      tags: [orders]
      summary: Create an order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '201':
          description: Order created.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Order:
      type: object
      required: [id, total]
      properties:
        id:
          type: string
          description: Server-generated order ID.
        total:
          type: number
          format: double
          description: Order total in cents.
        status:
          type: string
          enum: [pending, shipped, cancelled]

Markdown API reference

# Orders API v1.4.0

Create and track customer orders.

Spec version: `3.0.3`

## Base URLs

- `https://api.example.com/v1` — Production

## Authentication

| Scheme | Type | Details |
| --- | --- | --- |
| `bearerAuth` | http | scheme: `bearer`, bearer format: `JWT` |

## Contents

- [orders](#orders)
  - [GET /orders](#get-orders)
  - [POST /orders](#post-orders)

## orders

Order lifecycle endpoints

### GET /orders

**List orders**

Operation ID: `listOrders`

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `status` | query | string (`pending`, `shipped`, `cancelled`) | No | Filter by order status. |
| `limit` | query | integer (int32) | No | — |

**Responses**

| Code | Description | Schema |
| --- | --- | --- |
| `200` | A page of orders. | array of [Order](#order) |
| `401` | Missing or invalid token. | — |

### POST /orders

**Create an order**

**Request body** (`application/json`, required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Server-generated order ID. |
| `total` | number (double) | Yes | Order total in cents. |
| `status` | string (`pending`, `shipped`, `cancelled`) | No | — |

**Responses**

| Code | Description | Schema |
| --- | --- | --- |
| `201` | Order created. | — |

## Schemas

### Order

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Server-generated order ID. |
| `total` | number (double) | Yes | Order total in cents. |
| `status` | string (`pending`, `shipped`, `cancelled`) | No | — |

What the converter produces

Endpoint sections

Every path and method becomes a heading with its summary, description, operation ID, and a parameter table. Path-level parameters are merged into each operation.

Resolved schemas

Local $ref pointers resolve to field tables. Circular references stop safely instead of looping, and schema names link to the reference section.

Both spec versions

OpenAPI 3.x uses servers and components. Swagger 2.0 uses host, basePath, and definitions. Both convert to the same output.

How to Use OpenAPI to Markdown

Paste your OpenAPI 3.x or Swagger 2.0 spec, or upload the .yaml/.json file.
Choose whether to include a table of contents, tag grouping, the schema reference, and examples.
Review the generated Markdown API reference in the right pane.
Copy it or download api-reference.md, then paste it into your README or docs site.

Frequently Asked Questions

Which spec versions are supported?: OpenAPI 3.0 and 3.1, plus Swagger 2.0. Both JSON and YAML input work — the format is detected automatically. Swagger 2.0 fields like <code>host</code>, <code>basePath</code>, <code>schemes</code>, <code>definitions</code>, and <code>securityDefinitions</code> map to the same output sections as their OpenAPI 3 equivalents.
Does it resolve $ref pointers?: Local refs (<code>#/components/schemas/Pet</code>, <code>#/definitions/User</code>) resolve to real field tables, and schema names link to the schema reference section. Circular refs are detected and labelled instead of looping forever. Refs to external files or URLs cannot be fetched client-side, so they appear as a labelled placeholder — bundle your spec first if you need them inlined.
Is my spec uploaded anywhere?: No. Parsing and Markdown generation run entirely in your browser. Nothing is sent to a server, which makes this safe for internal or unreleased APIs.
Can I paste the output into Confluence or Jira?: Yes. Generate the Markdown here, then run it through the Markdown to Confluence or Markdown to Jira converter to get storage format or wiki markup.
Why are some description cells showing a dash?: A dash means that field has no description in the spec. Markdown table cells cannot be empty without breaking alignment, so blanks are filled with an em dash. Add <code>description</code> entries to your spec to fill them in.
What happens to operations without tags?: They are collected under a single "Endpoints" heading. Turn off "Group by tag" to put every operation under that one heading regardless of tags.

Related Tools

Markdown Editor

Free online Markdown editor with live preview. Write and preview Markdown in real-time with GitHub Flavored Markdown support.

WYSIWYG Markdown Editor

Rich text WYSIWYG editor that outputs clean Markdown. Free online visual Markdown editor.

Markdown to HTML

Convert Markdown to clean HTML code instantly. Free online Markdown to HTML converter with copy and download options.

HTML to Markdown

Convert HTML to clean Markdown instantly. Free online HTML to Markdown converter. Paste HTML and get Markdown output.

About OpenAPI to Markdown

Convert an OpenAPI 3.x or Swagger 2.0 spec into clean Markdown API documentation. Endpoints, parameters, request bodies, responses, and schemas. Runs in your browser. This tool runs entirely in your browser, so your content is not sent to a server. MarkdownMe provides free, fast, and reliable Markdown tools for developers, writers, and anyone who works with Markdown.