![header](https://github.com/fern/docs/assets/fern.png)
Learn how to create beautiful documentation in under 5 minutes using an OpenAPI specification (formerly Swagger).
Get inspired by API documentation built with Fern: Hume | MultiOn | Flagright | Traceloop | ElevenLabs
- Node 18 or higher
- A GitHub account
- Click on the Use this template button (found at the top right of this page). You must be logged into GitHub.
- Choose the option to create a new repository. Name it
fern-docs
.
Clone your newly created repository and open it in your favorite code editor (e.g., VS Code).
The files and folders discussed in the following steps will be inside the fern/
folder in your repository.
Open the fern.config.json
file, which looks like this:
{
"organization": "Petstore",
"version": "0.17.8"
}
Replace "Petstore"
with your own organization name within the quotes. Spaces are permitted. Leave the version
number unchanged.
Open the docs.yml
file and locate the url
, which looks like this:
instances:
- url: petstore-openapi.docs.buildwithfern.com
Replace petstore-openapi
with your own organization's name. Use only alphanumeric characters, hyphens, and underscores. Do not use spaces, and leave the rest of the URL (docs.buildwithfern.com
) unchanged.
Install the Fern CLI globally by running:
npm install -g fern-api
The CLI commands in the following steps must be run from within the root folder of your repository.
Run the following command:
fern generate --docs
You will be prompted to log in and connect your GitHub account.
Once the documentation is generated, you will receive the URL where your documentation is published. For example:
┌─
│ ✓ petstore-openapi.docs.buildwithfern.com
└─
# OR
┌─
│ ✓ MY_ORGANIZATION_NAME.docs.buildwithfern.com
└─
You must run fern generate --docs
after any modifications to re-generate and publish your documentation site.
To preview updates to your documentation before publishing changes, run fern generate --docs --preview
.
To use your own OpenAPI specification file or to update the existing one:
- Update or replace the OpenAPI specification file in the
openapi/
folder. - Note: Don't have an OpenAPI spec? Use Fern's simpler format to define your API. Learn more.
To modify the other docs pages:
- Update the Markdown files located in the
docs/pages/
folder, such aswelcome.mdx
.
To modify site styles and navigation, or to add new pages:
- See Writing Content.
To learn about Fern's built-in component library you can use in Markdown:
- See the Component Library.
If you wish to use a custom subdomain like https://docs.YOUR_ORGANIZATION.com
or a subpath like https://YOUR_ORGANIZATION.com/docs
, you can subscribe to the Starter plan. Once subscribed, update docs.yml
with the custom domain configuration:
- url: petstore-openapi.docs.buildwithfern.com
custom-domain: docs.petstore-openapi.com
For advanced documentation features and options, view the full configuration docs.
Good luck creating beautiful and functional documentation! 🌿
Need help? Set up a call with an expert or email us at support@buildwithfern.com.
The OpenAPI specification is a format for describing REST APIs. The specification consists of a single JSON or YAML file. OpenAPI was previously known as Swagger. Fern supports both OpenAPI (3.x) and Swagger (2.x). We refer to the specification as OpenAPI throughout our documentation.