OpenAPI

API Pages

OpenAPI

Reference OpenAPI endpoints in your docs pages

To describe your endpoints with OpenAPI, make sure you have a valid OpenAPI document in either JSON or YAML format that follows the OpenAPI specification.

Your document must follow OpenAPI specification 3.0+.

Configuration Quickstart

The fastest way to get started with OpenAPI is to add an openapi field to api in the settings file. This field can contain either the relative path to an OpenAPI document in your docs or the URL of a hosted OpenAPI document.

{
    // ... rest of settings
    "api": {
        "openapi": {
            "source": "./api/rest/openapi.yaml",
            "route": "docs/api/rest"
        }
    },
}

This will create a new route based on your OpenAPI specification at docs/api/rest/*.

You can also use URL-based paths to OpenAPI spec instead of local files.

Multi Spec Configuration

Creating multi API specs for more advanced use cases is also possible:

{
    // ... rest of settings
    "api": {
        "openapi": [
          {
            "source": "./api/rest/openapi.yaml",
            "route": "docs/api/rest"
          },
          {
            "source": "./api/webhooks/openapi.yaml",
            "route": "docs/api/webhooks"
          }
        ]
    }
}

Thanks to this configuration, you'll have two routes: docs/api/rest/* and docs/api/webhooks/*.

API Docs Generation Guides

The generator automatically creates documentation based on your OpenAPI specification
Uses OpenAPI tags to create logical groups of endpoints
Generates clean URLs from operationId when available
Organizes endpoints by path when no tags are specified
Groups related schemas with their endpoints
Links response schemas to their corresponding endpoints

All defaults can be overridden using the x-docs extension

X-Docs Extension

The x-docs extension provides additional configuration options to customize your API documentation beyond the standard OpenAPI specification. Use it to control sidebar structure, code snippets, and endpoint visibility.

To make your OpenAPI documentation more organized and user-friendly, you can customize the navigation structure using the x-docs extension. This allows you to group endpoints and schemas into logical sections and control their URLs.

Since xyd creates a sidebar by default based on tags and other OpenAPI Spec, x-docs gives you more control.

You can define a complete navigation structure using the sidebar property in the x-docs extension:

# ...
x-docs:
  route: docs/api-reference # or from docs.json
  sidebar:
    - group: API & Reference
      pages:
        - group: Endpoints
          pages:
            - group: Users
              path: users
              pages:
                - type: endpoint
                  key: GET /users
                  path: get

                - type: endpoint
                  key: GET /users/{userId}
                  path: userId

                - type: endpoint
                  key: createUserPostId # you can use operationId as well
                  path: posts/create

                - type: object
                  key: User
                  path: object

above example will create sidebar:

"API & Reference > Endpoints > Users":
    * [{title}]({route}/users/get)
    * [{title}]({route}/users/userId)
    * [{title}]({route}/users/posts/create)
    * [{title}]({route}/users/object)

Info

title comes from generated OpenAPI spec and route from docs.json/x-docs.route.

Learn More

Navigation Customization Details

Route

The route property defines the base URL path for your API documentation. This is where all your API documentation pages will be served from.

route: "docs/api/rest"

If you define route in docs.json it will overwrite the route in OpenAPI spec.

Type

The type property in the sidebar configuration specifies what kind of content will be displayed. There are two main types:

endpoint: Used for API endpoints. The key can be either:
- A path and method combination (e.g., GET /users)
- An operationId from your OpenAPI spec
object: Used for schema definitions. The key should match the schema name in your OpenAPI spec

Example:

x-docs:
  # ...
  pages:
    - type: endpoint
      key: GET /users

    - type: endpoint
      key: createUser

    - type: object
      key: User

Path

Adding a path for each of pages helps to create a clean and organized URLs in your API documentation. The path property determines the URL segment for each page in your documentation.

For example:

x-docs:
  route: docs/api/rest # or from docs.json
  sidebar:
    - group: API & Reference
      pages:
        - group: Users
          path: users # it's route + `/users` for all child pages
          pages:
            - type: endpoint
              key: GET /users
              path: get # route + `/users/get`
            - type: endpoint
              key: GET /users/{userId}
              path: get-by-id # route + `/users/get-by-id`

this configuration will generate URLs like:

/docs/api/rest/users/get
/docs/api/rest/users/get-by-id

The final URL is constructed by combining the base route with the path segments from each level of the sidebar configuration.

Request Code Snippets

You can also specify supported programming languages for request code snippets using x-docs.codeLanguages:

# ...
x-docs:
  codeLanguages:
    - javascript
    - python
    - java

this method generates code snippets based on specific request for defined languges.

Code Samples

If you have a code snippet already and dont wan't a generic, autogenerated one you can use x-codeSamples:

paths:
  /users:
    get:
      # ...
      x-codeSamples:
        - lang: bash
          label: List all users
          source: |
            curl -X GET https://api.example.com/users

        - lang: javascript
          label: List all users
          source: |
            const api = require('api-client');
            api.users.list();

        - lang: bash
          label: Get user by ID
          source: |
            curl -X GET https://api.example.com/users/123

        - lang: javascript
          label: Get user by ID
          source: |
            const api = require('api-client');
            api.users.get('123');

WebhooksComing Soon

Support for OpenAPI webhook documentation is currently in development and will be available in the future.

API Docs Demo

You can also check out our interactive API Docs Demo to see these features in action and experiment with different OpenAPI configurations in real-time.

OpenAPI Samples

Learn how to setup OpenAPI pages.

Custom Theme GraphQL