API reference

Markline turns an OpenAPI 3.0/3.1 document into a full reference: a left resource nav, per-resource pages with attribute and parameter tables, dark code rails (cURL / Node / Python / Go), and an inline request explorer.

Add a spec

content/
├── markline.json
└── api/
    └── openapi.json

"navigation": {
  "tabs": [
    { "id": "docs", "label": "Documentation", "href": "/", "match": ["__default__"], "groups": [] },
    { "id": "api", "label": "API reference", "href": "/api-reference", "match": ["/api-reference"], "openapi": true }
  ]
}

"api": { "baseUrl": "https://api.example.com", "playground": { "mode": "full", "proxy": "auto" } }

What you get

The reference is per-resource: one page per tag, opening on the first resource. Each page has:

• A resource summary + an Endpoints card listing the tag's operations.
• A "The object" section — attributes derived from the schema, with types, required/optional flags, enums, and a sample JSON.
• One section per endpoint — method + path, parameters (path / query / body) from the schema, and a dark code rail with cURL, Node, Python and Go samples generated from the operation, plus the example response.

Nested tags

Slash-separated tags — the convention NestJS emits from @ApiTags('store/orders') — become a nested sidebar. No config: Markline groups by shared prefix and title-cases each segment (with an acronym map, so fx → FX, api → API).

store/products       Store
store/orders    →      ├── Products
store/refunds          ├── Orders
admin/users            └── Refunds
admin/api/keys       Admin
                       ├── Users
                       └── API
                             └── Keys

• Parent groups are nav-only accordions (expand/collapse), opening to the active resource. Each leaf tag stays a normal resource page.
• URLs are unchanged — the slug is still the whole tag, so store/orders lives at /api-reference/store-orders and existing links keep working.
• Depth is arbitrary (admin/api/keys nests three levels); the page title shows the leaf (Keys) with an Admin / API breadcrumb.
• Single-segment tags (payments) are unchanged — plain top-level entries.

Code samples

Every endpoint gets a dark code rail. By default Markline generates four samples — cURL, Node, Python, Go — from the operation itself: the Node/Python/Go ones are SDK-style (client.<resource>.<method>(…)), inferred from the tag, operationId, and the body / path / query parameters. You shape the rail two ways.

Pick the generated languages

api.codeSamples chooses which generated languages appear, and in what order. It's a subset of "curl" | "node" | "python" | "go"; omit it and all four show.

"api": {
  "baseUrl": "https://api.example.com",
  "codeSamples": ["curl", "node"]   // just cURL + Node, in that order
}

How generated samples are named

There's no separate "SDK name" setting — the generated snippets build their identifiers from your spec. A sample like acme.payments.create({ … }) is assembled from four derived tokens:

So the two levers on the generated rails are info.title (the client name) and your tag names (the resource accessors). To match a real SDK exactly — custom client name, hand-written method signatures, a language Markline doesn't generate — reach for x-codeSamples.

Bring your own with x-codeSamples

To replace the generated rail on a specific operation, add the x-codeSamples extension to that operation in your OpenAPI document (not in markline.json). The older x-code-samples spelling is accepted too — Markline reads either, so specs written for Redoc/Stripe work unchanged.

"paths": {
  "/v1/payments": {
    "post": {
      "operationId": "createPayment",
      "summary": "Create a payment",
      "x-codeSamples": [
        {
          "lang": "ruby",
          "label": "Ruby",
          "source": "Acme::Payment.create(\n  amount: 1000,\n  currency: \"usd\",\n)"
        },
        {
          "lang": "php",
          "source": "$client->payments->create([\n  'amount' => 1000,\n  'currency' => 'usd',\n]);"
        }
      ]
    }
  }
}

Each entry has three fields:

This is the escape hatch for hand-written, copy-paste-correct examples: real SDK calls, framework-specific snippets, or languages Markline can't generate.

The playground

Write endpoints get an inline request explorer: an editable Authorization field, the request fields, a Send button, and the live response with status + latency. It's the same engine on every surface.

Events & webhooks

If your API emits webhooks or async events, Markline documents them alongside the endpoints that trigger them. Each resource grows an Events tab listing the events it can deliver — name, summary, payload schema, and a sample — and the two are cross-linked: an emitting endpoint shows a Triggers chip, and the event shows an Emitted by back-link to that endpoint. The tab only appears on resources that actually have events; a spec with none looks exactly as before.

Where events come from

Markline reads events from four sources and normalizes them into one model, so you can use whichever your toolchain already emits:

For root webhooks / x-webhooks, each entry is a Path Item — Markline takes its first method operation and reads summary, description, the operation's tags, and the JSON request body as the payload. A root webhook only appears on a resource if its operation carries a matching tags entry; untagged webhooks are parsed but have no resource to attach to.

The x-events extension

x-events is the most direct way to declare events. It takes either a map of name → definition, or an array of names (references to events defined elsewhere — no inline payload):

"x-events": {
  "project.created": {
    "summary": "A new project was created.",
    "description": "Emitted once the project is provisioned and ready.",
    "payload": { "$ref": "#/components/schemas/Project" },
    "guide": "/guides/webhooks#project-created"
  }
}

"x-events": ["project.created", "project.deleted"]   // name-only references

Each definition field is optional:

Tag level vs. operation level changes how the event is wired:

• On an operation (paths.<path>.<method>.x-events), the event inherits that operation's tags, so it groups onto those resources — and because an endpoint triggers it, the endpoint gets a Triggers chip and the event an Emitted by back-link.
• On a tag (tags[].x-events), the event attaches to that resource only, with no emitter back-link. Use this for events not tied to a single endpoint — delivered by an external processor, a batch job, or a state change.

Markline merges the two per resource and de-duplicates by event name, so an event declared on both a tag and an operation appears once.

From NestJS

NestJS has no @ApiCallbacks, but @ApiExtension is a clean fit — and it's why x-events exists. Annotate the handler that causes the event; Markline aggregates it onto the resource automatically (no document-root wiring):

import { ApiExtension, ApiExtraModels, ApiTags, getSchemaPath } from '@nestjs/swagger';
 
@ApiTags('cards')
@ApiExtraModels(CardCreatedEvent)   // emits the payload into components.schemas
@Controller('cards')
export class CardsController {
  @Post()
  @ApiExtension('x-events', {
    'card.created': {
      summary: 'A new card was issued',
      payload: { $ref: getSchemaPath(CardCreatedEvent) },
      guide: '/guides/webhooks#card-created',
    },
  })
  create() { /* … */ }
}

• @ApiExtraModels(CardCreatedEvent) makes getSchemaPath(...) resolve — without it the $ref points at a schema that was never emitted.
• The event inherits @ApiTags('cards'), so it lands on the Cards resource and POST /cards gets the Triggers chip.
• @ApiExtension requires an x--prefixed key and an object value — both hold. Placed on the controller class it applies to every route; on a handler, just that operation.

Reuse a shared set with a small composed decorator:

import { applyDecorators } from '@nestjs/common';
import { ApiExtension } from '@nestjs/swagger';
 
export const Emits = (events: Record<string, unknown>) =>
  applyDecorators(ApiExtension('x-events', events));
 
// @Emits({ 'card.created': { summary: 'A new card was issued', payload: { $ref: getSchemaPath(CardCreatedEvent) } } })

MDX overlays

Layer authored MDX on top of the generated reference — full components (callouts, tables, tabs) included:

api/
├── openapi.json
├── introduction.mdx              # replaces the whole reference landing
├── sections/<tag>.mdx            # rich intro for a resource (overrides the tag description)
└── operations/<operationId>.mdx  # extra prose on one operation page

• sections/<tag>.mdx renders as the resource intro. The filename is the slugified tag — Payment Methods → payment-methods.mdx.
• operations/<operationId>.mdx renders between the endpoint path and the auto-generated parameters.

AI & page actions

Every resource section carries the same affordances as the docs: Copy for LLM (copies the section as Markdown), View as Markdown, and — when Ask AI is enabled — Ask about this section, which opens the docked assistant with that section as context.

Versions

The reference header shows a version selector. With a single spec it surfaces the spec's info.version (a semver 1.4.2 → v1 · 1.4.2; a date 2025-06-01 → shown once, verbatim).

With multiple versions configured, each version ships its own <id>/api/openapi.json, served at /api-reference/<id> — the selector switches the spec in place and every link stays under that version's prefix. See Versions & i18n for the folder layout.