Guide
Turning an OpenAPI or Swagger spec into Markdown documentation
An OpenAPI document is the machine-readable description of an HTTP API: its paths, operations, parameters, request bodies, responses and data models. It is excellent input for tools and awkward for people, because a long YAML file with nested schemas and references is hard to skim. Markdown, on the other hand, renders in a README, a wiki, a pull request and a static site generator. This page converts one into the other.
What the page accepts
Paste or open the file. The text is first tried as JSON and, if that fails, read as YAML, so you do not need to say which it is. A document with an openapi field (version 3.0 or 3.1) or a swagger field (version 2.0) and a paths section is accepted. Anything else produces an error naming the missing part, for example a document that has no paths section. The page does not check the document against the OpenAPI schema, so a file with mistakes may still convert as far as it can.
What the Markdown contains
The output starts with the API title, the version, the specification version and the description. It continues with the servers, then a table of all operations with method, path and summary. Operations are grouped under their first tag; each gets a heading, its summary, the operation ID, a table of parameters (name, location, type, whether it is required, description), the request body if there is one, and a table of responses with status, description and body type. At the end come the schemas, one table of properties each.
References
Specifications reuse definitions through $ref pointers such as #/components/schemas/Pet. The page follows pointers that start with a hash and shows the resolved type name or properties where they are used. It never fetches anything: a pointer to another file or a URL would need the network, and this page keeps all of your text in the browser. If your specification relies on other files, bundle it into one file first.
Options
“Include examples” adds the example values found in the specification to parameters and bodies. “Include the schemas section” appends the property tables for the models. Turn both off for a short overview that is easy to read in a README. Like the inputs of other tools on this site, the text is kept in your browser’s local storage so that a reload does not lose your work; clear the box if the specification contains anything private.
A worked example
The Sample button loads a small pet store API in YAML: version 1.2.0, one server, and two paths. The output opens with the title “Pet Store”, version 1.2.0 and OpenAPI 3.0.3, followed by the line “3 operations:” and a table listing GET /pets (List pets), POST /pets (Add a pet) and GET /pets/{petId} (Get one pet). Under the “pets” heading, GET /pets shows its operation ID listPets and a parameters table with limit, in the query, optional, an integer. The NewPet and Pet schemas appear in the schemas section.
Limits
The page documents what the file says. It does not execute requests, test whether examples match schemas, or draw diagrams. Security schemes, callbacks, webhooks and links are not rendered in detail. For very large specifications the output is long, so the options for examples and schemas help. OpenAPI 3.1 documents are read, but keywords specific to JSON Schema 2020-12 are shown only as far as the property tables allow.
Related tools
- JSON Schema Validator checks data against the schemas used in a specification.
- YAML to JSON converts the file to JSON if a tool needs it.
- JSON Formatter tidies a JSON specification before conversion.
- Markdown Table Generator helps with hand-written tables in the same documents.
Checked against the current version of the OpenAPI to Markdown on .