Fern DefinitionAdvanced

Availability in Fern Definition

You can add availability to an endpoint, type, or property within your Fern Definition. You can configure the availability of sections in your API reference documentation in your docs.yml file.

Endpoints, types, and properties

Availability can be:

  • in-development which means it is being worked on; will show a Beta tag
  • pre-release which means it is available; will show a Beta tag
  • deprecated which means it will be removed in the future; will show a Deprecated tag
  • generally-available which means it is stable and available for use; will show a GA tag

Endpoint

pet.yml
1service:
2  base-path: /pet
3  auth: true
4  endpoints:
5    add:
6      availability: deprecated
7      display-name: Add pet
8      docs: Add a new Pet to the store
9      method: POST
10      path: ""
11      request: AddPetRequest
12      response: Pet

In Fern Docs, this will look like:

Screenshot showing a deprecated tag next to an endpoint in API Reference docs

Type

pet.yml
1  Pet:
2    properties:
3      id: 
4        type: integer
5        docs: A unique ID for the Pet
6      name: 
7        type: string
8        docs: The first name of the Pet
9      photoUrls: 
10        type: list<string>
11        docs: A list of publicly available URLs featuring the Pet
12        availability: generally-available
13      category: 
14        type: optional<Category>
15        availability: pre-release
16
17  Category:
18    properties:
19      id: optional<integer>
20      name: optional<string>

In Fern Docs, this will look like:

Screenshot showing a beta tag next to a type in API Reference docs

Property

pet.yml
1  Pet:
2    properties:
3      id: 
4        type: integer
5        docs: A unique ID for the Pet
6      name: 
7        type: string
8        docs: The first name of the Pet
9      photoUrls: 
10        type: list<string>
11        docs: A list of publicly available URLs featuring the Pet
12        availability: deprecated
13      category: optional<Category>

In Fern Docs, this will look like:

Screenshot showing a deprecated tag next to a type's property in API Reference docs

Sections

You can set the availability for the entire API reference or for specific sections in your docs.yml configuration. Options are: stable, generally-available, in-development, pre-release, deprecated, or beta.

When you set the availability of a section, all of the endpoints in that section are automatically marked with that availability unless explicitly set otherwise.

docs.yml
1navigation: 
2  - api: API Reference
3    availability: generally-available
4    layout: 
5      - section: My Section
6        availability: beta
7        icon: flower
8        contents: 
9        # endpoints here