Write markdown content in your API reference

Fern Docs allows you to write markdown content in your API reference documentation. This feature is useful for providing additional context, examples, or explanations for your API endpoints. There are a few ways to accomplish this:

In OpenAPI

If you’re using OpenAPI to define your API, you can include markdown content in your OpenAPI specification.

For example, you can include a callout in the description field of an endpoint:

1
paths:
2
  /pets:
3
    get:
4
      summary: List all pets
5
      description: |
6
        Get a list of all pets in the system.
7
8
        <Note>This endpoint requires authentication.</Note>

In Fern Definition

If you’re using Fern’s simpler API definition format, you can include markdown content in your API definition.

For example, you can include a callout in the docs field of an endpoint:

1
service:
2
  endpoints:
3
    get:
4
      path: /pets
5
      docs: |
6
        Get a list of all pets in the system.
7
8
        <Note>This endpoint requires authentication.</Note>

Adding a summary page

You can also create a markdown page that provides an overview of your API reference. This page can include general information about your API, such as authentication requirements, rate limits, or other important details.

To add a summary page, create a markdown file in your fern/ folder and link to it in your docs.yml file:

1
navigation:
2
  - api: API Reference
3
    summary: ./pages/api-summary.mdx

By including the summary field, the API Reference section title will link to the api-summary.mdx page.

Adding markdown content between endpoints

In addition to adding markdown content to individual endpoints, you can also include markdown content between endpoints in your API reference. This content can provide context or explanations that apply to multiple endpoints.

This feature requires you to use the layout field in your docs.yml file, which is described in the Reorder your API reference guide.

To add markdown content between endpoints, create a markdown file in your fern/ folder and link to it in your docs.yml file:

1
navigation:
2
  - api: API Reference
3
    layout:
4
      - pet:
5
          - page: Pet CRUD
6
            path: ./pages/pet-crud.mdx
7
          - addPet
8
          - updatePet
9
          - deletePet
10
          - page: Pet Search
11
            path: ./pages/pet-search.mdx
12
          - findPets
13
          - findPetsByStatus
14
          - findPetsByTags
15
          - findPetsByType
16
          - findPetsByBreed

Aside component

When writing markdown content for your API reference, the <Aside> component can be useful for providing additional information or context. For example, you can use the <Aside> component to explain how to authenticate with your API or provide examples of request and response payloads.

1
---
2
title: Pet CRUD operations
3
---
4
5
Welcome to the Pet CRUD operations section. This section provides an overview of the CRUD operations for managing pets in the system.
6
7
<Aside>
8
### Authentication
9
```json
10
{
11
  "username": "admin",
12
  "password": "password"
13
}
14
```
15
16
### Request payload
17
```json
18
{
19
  "name": "Fido",
20
  "breed": "Golden Retriever",
21
  "age": 5
22
}
23
```
24
</Aside>