Basedoc projects can contain API documentation pages. These pages are different from regular docs pages as they can be configured to contain auto-generated content so your readers and AI agents can easily digest each API endpoint.

You can describe each endpoint in the file's frontmatter, and Basedoc will auto-generate the API documentation page for you.

Pages are flexible and you can include and customise different sections of the API pages with "components".

Set your API URL in basedoc.json

The first thing to do is to define your API URL in the project's configuration file.

The URL you provide in api.custom.serverUrl will be used as the default for all of your API docs. This server URL can be overridden on a per-page basis.

"api": {
  "custom": {
    "serverUrl": "https://api.example.com"
  }
},

This will be used to generate the API documentation page for you.

API docs frontmatter

Each API docs page can have its own API-specific frontmatter. This allows you to describe your endpoints in a simple way.

API frontmatter is similar to OpenAPI/Swagger specs, but it's designed to be much easier to read and write and can be easily converted to/from OpenAPI/Swagger specs.

Here's an example of a simple API docs page frontmatter:

---
# Regular page frontmatter
title: "API Documentation"
description: "This is a description of the API documentation page."

# API-specific frontmatter
api:
  endpoint:
    post /v1/users:
      summary: Create a user
      auth: bearer
      request:
        body:
          schema:
            email: string
      responses:
        201:
          schema:
            id: string
---

Here the endpoint is a simple POST request containing a JSON body with an email field. The response is a 201 status code with a JSON body containing an id field.

The syntax supports more complicated endpoints with query parameters, headers, and more.

Read more about the API docs frontmatter syntax.

API docs components

Basedoc processes the frontmatter and auto-generates the API documentation page for you.

There are multiple components available so you can build your pages exactly how you want them to look.

The simplest way to build a page is as follows:

---
title: "Endpoint name"
api:
  # API frontmatter Here
---

## Overview
<Endpoint /​>

## Request parameters
<Params /​>

## Request body
<Body /​>

## Responses
<Responses /​>

This will render a full page with the endpoint URL and description, followed by information about any request parameters and body, then listing all available responses and their schemas.

Code examples for requests are also generated, so readers can see how to use the endpoint in practice.

You can customise the page by adding Markdown content to the page or using "sub-components".

## Overview
<Endpoint /​>

## Request parameters

### Headers

<Params location="headers" /​>

### Path parameters

<Params location="path" /​>

## Request body

<Field name="email" /​>

## Responses

<Response code="200" /​>
<Response code="400" /​>
<Response code="500" /​>

Read more about API docs components.