Skip to main content

You can manually define API endpoints in individual MDX pages. This approach is useful for small APIs or prototyping.

Setup

1

Configure your API settings

In your docs.json file, define your base URL and authentication method.

Example docs.json
"api": {
  "mdx": {
    "server": "https://api.acme.com/",
    "auth": {
      "method": "key",
      "name": "x-api-key"
    }
  }
}

If you want to hide the API playground, set the display field to none. You don't need to include an authentication method if you hide the playground.

"api": {
  "playground": {
    "display": "none"
  }
}

Find a full list of API configurations in Settings.

2

Create your endpoint pages

Create an MDX file for each endpoint. Define the title and api in the frontmatter:

---
title: 'Create new user'
api: 'POST /v1/users'
---

The api frontmatter field accepts either a full URL or a relative path:

  • Full URL like POST https://api.acme.com/v1/users. The server field in docs.json is ignored for that endpoint.
  • Relative path like POST /v1/users. Requires a server field in docs.json. The server URL is prepended to the path.

Specify path parameters by wrapping them in {}:

https://api.example.com/v1/endpoint/{userId}

To override the global playground display mode for a specific page, add playground to the frontmatter:

---
title: 'Create new user'
api: 'POST https://api.docfiy.com/user'
playground: 'none'
---

Options:

  • playground: 'interactive' - Display the interactive playground (default)
  • playground: 'simple' - Display a copyable endpoint with no playground
  • playground: 'none' - Hide the playground entirely
3

Add parameters and responses

Use parameter and response fields to document your endpoint's parameters and return values.

<ParamField path="userId" type="string" required>
  Unique identifier for the user
</ParamField>

<ParamField body="email" type="string" required>
  User's email address
</ParamField>

<ResponseField name="id" type="string" required>
  Unique identifier for the newly created user
</ResponseField>

<ResponseField name="email" type="string" required>
  User's email address
</ResponseField>
4

Add your endpoints to your docs

Add your endpoint pages to the navigation by updating the pages field in your docs.json:

docs.json
"navigation": {
  "tabs": [
    {
      "tab": "API Reference",
      "groups": [
        {
          "group": "Users",
          "pages": [
            "api-reference/users/create-user",
            "api-reference/users/get-user",
            "api-reference/users/update-user"
          ]
        },
        {
          "group": "Orders",
          "pages": [
            "api-reference/orders/create-order",
            "api-reference/orders/list-orders"
          ]
        }
      ]
    }
  ]
}

Each page path corresponds to an MDX file in your docs repository. For example, api-reference/users/create-user.mdx. Learn more about structuring your docs in Navigation.

Using OpenAPI endpoints in navigation

If you have an OpenAPI specification, you can reference endpoints directly in your navigation without creating individual MDX files. Reference specific endpoints by including the OpenAPI file path and the endpoint:

docs.json
"navigation": {
  "pages": [
    "introduction",
    "/path/to/users-openapi.json POST /users",
    "/path/to/orders-openapi.json GET /orders"
  ]
}

You can also set a default OpenAPI spec for a navigation group and reference endpoints by method and path:

docs.json
{
  "group": "API reference",
  "openapi": "/path/to/openapi-v1.json",
  "pages": [
    "overview",
    "authentication",
    "GET /users",
    "POST /users",
    {
      "group": "Orders",
      "openapi": "/path/to/openapi-v2.json",
      "pages": [
        "GET /orders",
        "POST /orders"
      ]
    }
  ]
}

For more details on OpenAPI integration, see OpenAPI setup.

Enable authentication

You can set authentication globally in docs.json or override it on individual pages using the authMethod field in frontmatter. A page-specific method overrides the global setting.

Bearer token

"api": { "mdx": { "auth": { "method": "bearer" } } }

Basic authentication

"api": { "mdx": { "auth": { "method": "basic" } } }

API key

"api": { "mdx": { "auth": { "method": "key", "name": "x-api-key" } } }

None

To disable authentication on a specific page, set authMethod to none:

Page Metadata
---
title: "Your page title"
authMethod: "none"
---