OpenAPI reference
Point Typemark at an OpenAPI spec and it builds an API reference, with an overview page and one page per endpoint, every time you publish.
2026年11月19日更新4分で読めます
Add an OpenAPI 3 or Swagger 2 spec to your repository, reference it in your navigation, and Typemark generates your API reference: an overview page plus one page per endpoint. The pages rebuild on every deploy, so they stay in step with the spec.
Add your spec
Put the spec in your repository
Use a JSON or YAML file, such as
openapi.jsonoropenapi.yaml. Files ending in.yamlor.ymlare read as YAML; everything else as JSON.Reference it in typemark.json
Add an entry with
sourceto a group'spages, using the file's path from the root of your repository:{ "navigation": { "tabs": [ { "tab": "API Reference", "groups": [ { "group": "Endpoints", "pages": [{ "source": "openapi.json" }] } ] } ] } }Publish
Commit the change. The next build generates the pages.
From project settings
You can also do it without touching typemark.json. Open your project's settings and find API Documentation.
- Click Upload to add a
.json,.yaml, or.ymlfile. Typemark checks that it's a spec file and commits it to the root of your repository. - Or type the path of a spec that's already in your repository.
When you save, Typemark adds the spec to an Endpoints group in an API Reference tab, creating them if they don't exist, and rebuilds your site. Clear the field and save to remove the generated pages.
What gets generated
The overview page
The overview page sits in your navigation where you put the source entry. Its title comes from info.title in the spec, and it shows:
info.description- the version, from
info.version - the base URL, from the first entry in
servers - a table of every endpoint with its method, path, and summary
Its slug is the spec's file name without the extension. A file named openapi is the exception and gets api-reference.
| Spec file | Overview slug |
|---|---|
openapi.json | api-reference |
specs/payments.yaml | payments |
Endpoint pages
Each GET, POST, PUT, PATCH, and DELETE operation gets its own page. The title is the operation's summary, or the method and path when there's no summary. Each page shows:
- the method and path, with a Deprecated label if the operation is deprecated
- the operation's
description - Parameters: name, location, type, required, and description
- Request Body: the description and the top-level properties of the
application/jsonschema - Responses: one section per status code, with its description and the top-level properties of its
application/jsonschema
Endpoint slugs live under the overview's slug and combine the method with the path:
| Operation | Slug |
|---|---|
GET /users | api-reference/get-users |
POST /users | api-reference/post-users |
GET /users/{id} | api-reference/get-users-id |
Sidebar
The overview page and any endpoints without a tag are listed in the group that holds your spec. Each tag gets its own group, named after the tag, right after it; an endpoint goes in the group of its first tag. Each sidebar link shows the HTTP method next to the title.
How schemas are shown
| In the spec | Shown as |
|---|---|
$ref to #/components/... | The referenced schema's properties |
allOf | The properties of every sub-schema, merged |
oneOf, anyOf | The types joined with |, like string | integer |
enum | The allowed values, like "active" | "archived" |
| An array | The item type with [], like string[] |
Only top-level properties are listed. Nested objects show as object.
Write an endpoint's page
When an endpoint needs more than the spec says, such as how a flow works or which payment methods respond how, write a page for it and name the endpoint in its frontmatter with openapi:
---
title: Create a payment
openapi: "openapi.json POST /payment"
---
Card payments redirect the customer to their bank. Other methods answer at once.
The page shows everything the endpoint's generated page shows, with your text after the endpoint's description: the method and path, the description, your text, then Parameters, Request Body, and Responses. It's a regular page otherwise: it keeps its own address and its place in navigation, and opens in the editor like any other.
- The spec is a path from the root of your repository, like a
sourceentry, or from yourdocs_root. You can leave it out (openapi: "POST /payment"): Typemark then looks in the specs your navigation lists, in order. The spec doesn't have to be in your navigation. - The method and path are written as they are in the spec, such as
GET /users/{id}. - The title is the endpoint's
summarywhen the page has notitle, and the description works the same way. The sidebar shows the method next to the title. - If Typemark can't find the endpoint, the page shows only your text, and the deployment lists a warning saying why.
typemark checkreports it before you publish.
When a spec is also in your navigation with { "source": ... }, its generated pages stay too, so you'll have both. To show only the pages you wrote, leave the spec out of navigation and write a page for each endpoint. Pages imported from Mintlify and ReadMe use the same openapi frontmatter.
Tips
- Give every operation a
summary. It becomes the page title and the sidebar label. - Tag your operations. Tags turn a long list of endpoints into sidebar groups readers can scan.
- Keep
serversup to date (host,basePath, andschemesin Swagger 2). The first URL is the base URL shown on the overview page. - To mention an endpoint on another page, use an endpoint line. It links to the page you wrote for the endpoint, or else its generated page.
- Preview the pages before you publish with
typemark dev, signed in.typemark checkfinds a spec that won't parse: the publish would fail with its error.