OpenAPI setup

OpenAPI is a specification for describing APIs. Docfiy supports OpenAPI 3.0 and 3.1 documents to generate interactive API documentation and keep it up to date.

Add an OpenAPI specification file

To document your endpoints with OpenAPI, you need one or more valid OpenAPI specifications in either JSON or YAML format that follow the OpenAPI specification 3.0 or 3.1.

Add OpenAPI specifications to your documentation repository or host them online where you can access the specifications by URL. Specifications stored in your repository are served as downloadable files at their path on your docs domain. For example, https://your-domain/docs/openapi.json.

Reference any number of OpenAPI specifications in the navigation element of your docs.json to create pages for your API endpoints. Each specification file generates its own set of endpoints.

Describe your API

Use the following resources to learn about and construct your OpenAPI specification.

• Swagger's OpenAPI Guide to learn the OpenAPI syntax.
• The OpenAPI specification Markdown sources to reference details of the latest OpenAPI specification.
• Swagger Editor to edit, validate, and debug your OpenAPI document.
• The Mint CLI to validate your OpenAPI document with the command: mint validate.

Specify the base URL for your API

To enable the API playground, add a servers field to your OpenAPI specification with your API's base URL.

{
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ]
}

In an OpenAPI specification, different API endpoints are specified by their paths, like /users/{id} or /. The base URL defines where these paths should be appended. For more information on how to configure the servers field, see API Server and Base Path in the OpenAPI documentation.

The API playground uses these server URLs to determine where to send requests. If you specify multiple servers, a dropdown allows users to toggle between servers. If you do not specify a server, the API playground uses simple mode since it cannot send requests without a base URL.

If your API has endpoints that exist at different URLs, you can override the servers field for a given path or operation.

Specify authentication

To enable authentication in your API documentation and playground, configure the securitySchemes and security fields in your OpenAPI specification. The API descriptions and API playground add authentication fields based on the security configurations in your OpenAPI specification.

{
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}

{
  "security": [
    {
      "bearerAuth": []
    }
  ]
}

Common authentication types include:

• API Keys: For header, query, or cookie-based keys.
• Bearer: For JWT or OAuth tokens.
• Basic: For username and password.

If different endpoints within your API require different methods of authentication, you can override the security field for a given operation.

For more information on defining and applying authentication, see Authentication in the OpenAPI documentation.

Set default values for security schemes

Use the x-default extension on a security scheme to pre-fill the authentication field in the API playground. This is useful for providing placeholder values or test credentials that help users get started quickly.

{
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "x-default": "your-api-key-here"
      }
    }
  }
}

The x-default extension supports apiKey and http bearer security scheme types. The value appears as the default input in the playground's authentication fields.

You can also use x-default on any schema property in your OpenAPI specification to set a default value in the API playground without affecting the default field in the schema definition.

Let visitors download your spec

Opt into a "Download API spec" entry in the page context menu by adding "download-spec" to contextual.options in your docs.json:

"contextual": {
  "options": ["copy", "download-spec", "chatgpt", "claude"]
}

When enabled, clicking the option downloads your OpenAPI spec directly. Deployments with multiple specs receive them bundled as api-specs.zip. The option is hidden for deployments behind auth or userAuth to prevent leaking spec contents from authenticated docs.

Customize your endpoint pages

Customize your endpoint pages by adding the x-mint extension to your OpenAPI specification. The x-mint extension gives you additional control over how your API documentation generates and displays.

Metadata

Override the default metadata for generated API pages by adding x-mint: metadata to any operation. You can use any metadata field that would be valid in MDX frontmatter except for openapi.

{
  "paths": {
    "/users": {
      "get": {
        "summary": "Get users",
        "description": "Retrieve a list of users",
        "x-mint": {
          "metadata": {
            "title": "List all users",
            "sidebarTitle": "List users",
            "description": "Fetch paginated user data with filtering options",
            "og:title": "Display a list of users"
          }
        },
        "parameters": [
          {
            // Parameter configuration
          }
        ]
      }
    }
  }
}

You can also control playground display per endpoint using the playground and groups metadata fields:

{
  "paths": {
    "/admin/users": {
      "post": {
        "summary": "Create admin user",
        "x-mint": {
          "metadata": {
            "playground": "auth",
            "groups": ["admin"],
            "public": true
          }
        }
      }
    }
  }
}

This configuration makes the page publicly visible while restricting the interactive playground to authenticated users in the admin group.

Content

Add content before the auto-generated API documentation using x-mint: content. The x-mint: content extension supports all Docfiy MDX components and formatting.

{
  "paths": {
    "/users": {
      "post": {
        "summary": "Create user",
        "x-mint": {
          "content": "## Prerequisites\n\nThis endpoint requires admin privileges and has rate limiting.\n\n<Note>User emails must be unique across the system.</Note>"
        },
        "parameters": [
          {
            // Parameter configuration
          }
        ]
      }
    }
  }
}

href

Set the URL of the autogenerated endpoint page using x-mint: href. When x-mint: href is present, the generated API page uses the specified URL instead of the default autogenerated URL.

{
  "paths": {
    "/legacy-endpoint": {
      "get": {
        "summary": "Legacy endpoint",
        "x-mint": {
          "href": "/deprecated-endpoints/legacy-endpoint"
        }
      }
    },
    "/documented-elsewhere": {
      "post": {
        "summary": "Special endpoint",
        "x-mint": {
          "href": "/guides/special-endpoint-guide"
        }
      }
    }
  }
}

Parameter pills

Annotate parameters in the API reference and playground with custom pill labels using x-mint.pre and x-mint.post on any schema. Pre pills render before the parameter name and post pills render after it, alongside Docfiy's built-in pills like required, read-only, and write-only.

Both fields accept an array of strings. Each string becomes its own pill.

{
  "components": {
    "schemas": {
      "User": {
        "properties": {
          "email": {
            "type": "string",
            "x-mint": {
              "pre": ["PII"],
              "post": ["indexed", "unique"]
            }
          }
        }
      }
    }
  }
}

To surface arbitrary OpenAPI spec fields as pills across every parameter without editing each schema, configure api.params.post in your docs.json. List the field keys you want to display, and Docfiy reads each value from the schema and renders matching pills automatically.

{
  "api": {
    "params": {
      "post": ["nullable", "x-internal"]
    }
  }
}

With this configuration, a property like { "type": "string", "nullable": true, "x-internal": "admin" } renders nullable and admin pills next to its name. Post pills appear in this order: built-in pills (read-only, write-only), then api.params.post config-driven pills, then per-property x-mint.post pills.

Group display names

Set a custom display name for a tag's navigation group using the x-group extension on a tag object. By default, Docfiy uses the tag name as both the navigation group label and the URL path segment. The x-group extension overrides the group label while keeping the tag name for the URL.

This is useful when you want a human-readable group name that differs from the tag used in your API paths.

{
  "tags": [
    {
      "name": "user-management",
      "description": "Endpoints for managing users",
      "x-group": "User Management"
    }
  ],
  "paths": {
    "/users": {
      "get": {
        "tags": ["user-management"],
        "summary": "List users"
      }
    }
  }
}

In this example, the navigation group displays as "User Management" but the generated page URL still uses the user-management tag name as its path segment.

Auto-populate API pages

Add an openapi field to any navigation element in your docs.json to automatically generate pages for OpenAPI endpoints. You can control where these pages appear in your navigation structure, as dedicated API sections or with other pages.

The openapi field accepts either a path in your docs repo or a URL to a hosted OpenAPI document.

Generated endpoint pages have these default metadata values:

• title: The operation's summary field, if present. If there is no summary, Docfiy generates the title from the HTTP method and endpoint.
• description: The operation's description field, if present.
• version: The version value from the parent anchor or tab, if present.
• deprecated: The operation's deprecated field. If true, a deprecated label appears next to the endpoint title in the side navigation and on the endpoint page.

There are two approaches for adding endpoint pages into your documentation:

1. Dedicated API sections: Reference OpenAPI specs in navigation elements for dedicated API sections.
2. Selective endpoints: Reference specific endpoints in your navigation alongside other pages.

Dedicated API sections

Generate dedicated API sections by adding an openapi field to a navigation element and no other pages. All endpoints in the specification appear in the generated section.

"navigation": {
  "tabs": [
    {
        "tab": "API Reference",
        "openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
    }
  ]
}

To organize multiple OpenAPI specifications in separate sections of your documentation, assign each specification to a different group in your navigation hierarchy. Each group can reference its own OpenAPI specification.

"navigation": {
  "tabs": [
    {
      "tab": "API Reference",
      "groups": [
        {
          "group": "Users API",
          "openapi": {
            "source": "/path/to/users-openapi.json",
            "directory": "users-api-reference"
          }
        },
        {
          "group": "Admin API",
          "openapi": {
            "source": "/path/to/admin-openapi.json",
            "directory": "admin-api-reference"
          }
        }
      ]
    }
  ]
}

Selective endpoints

When you want more control over where endpoints appear in your documentation, you can reference specific endpoints in your navigation. This approach lets you generate pages for API endpoints alongside other content. You can also use this approach to mix endpoints from different OpenAPI specifications.

Set a default OpenAPI spec

Configure a default OpenAPI specification for a navigation element. Then reference specific endpoints in the pages field.

"navigation": {
  "tabs": [
    {
      "tab": "Getting started",
      "pages": [
        "quickstart",
        "installation"
      ]
    },
    {
      "tab": "API reference",
      "openapi": "/path/to/openapi.json",
      "pages": [
        "api-overview",
        "GET /users",
        "POST /users",
        "guides/authentication"
      ]
    }
  ]
}

Any page entry matching the format METHOD /path generates an API page for that endpoint using the default OpenAPI specification.

OpenAPI spec inheritance

Child navigation elements inherit their parent's OpenAPI specification unless they define their own.

{
  "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"
      ]
    }
  ]
}

Individual endpoints

Reference specific endpoints without setting a default OpenAPI specification by including the file path. You can reference endpoints from multiple OpenAPI specifications in the same documentation section.

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

This approach is useful when you need individual endpoints from different specifications, only want to include select endpoints, or want to include endpoints alongside other types of documentation.

Create MDX pages from your OpenAPI specification

For more granular control over individual endpoint pages, create MDX pages from your OpenAPI specification. This lets you customize page metadata, content, and reorder or exclude pages in your navigation while still using the auto-generated parameters and responses.

There are two ways to document your OpenAPI specification with individual MDX pages:

• Document endpoints with the openapi field in the frontmatter.
• Document data models with the openapi-schema field in the frontmatter.

Document endpoints

Create a page for each endpoint and specify which OpenAPI operation to display using the openapi field in the frontmatter.

The method and path must exactly match your OpenAPI spec. If you have multiple OpenAPI specifications, include the path to the correct specification in your reference. You can also reference external OpenAPI URLs in docs.json.

Autogenerate endpoint pages

To autogenerate MDX files from your OpenAPI specification, use the Docfiy scraper.

npx @docfiy/scraping@latest openapi-file <path-to-openapi-file> -o <folder-name>

Document data models

Create a page for each data structure defined in your OpenAPI specification's components.schemas using the openapi-schema field in the frontmatter.

If you have schemas with the same name in multiple files, specify the OpenAPI file:

Webhooks

Webhooks are HTTP callbacks that your API sends to notify external systems when events occur. OpenAPI 3.1+ documents support webhooks.

Add a webhooks field to your OpenAPI document alongside the paths field.

For more information on defining webhooks, see Webhooks in the OpenAPI documentation.

To create an MDX page for a webhook (OpenAPI 3.1+), use webhook instead of an HTTP method:

---
title: "Order updated webhook"
description: "Triggered when an order is updated"
openapi: "openapi.json webhook orderUpdated"
---

The webhook name must exactly match the key in your OpenAPI spec's webhooks field.

Callbacks

Callbacks describe out-of-band requests that your API sends to a URL provided by the caller, such as event notifications tied to a specific operation. When an OpenAPI operation defines callbacks, Docfiy renders them on the endpoint page in a collapsible section between the request body and response sections. Each callback shows its HTTP method, expression, and reuses the same body and response components as the parent operation.

For more information on defining callbacks, see Callbacks in the OpenAPI documentation.

Define callbacks on the operation in your OpenAPI spec:

paths:
  /subscribe:
    post:
      summary: Subscribe to events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                callbackUrl:
                  type: string
                  format: uri
      responses:
        "201":
          description: Subscription created
      callbacks:
        orderUpdated:
          "{$request.body#/callbackUrl}":
            post:
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      type: object
                      properties:
                        orderId:
                          type: string
                        status:
                          type: string
              responses:
                "200":
                  description: Callback received