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:
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:
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:
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 Customize 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:
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.