Skip to navigation
Fern DefinitionAdvanced

Availability in Fern Definition

View as Markdown

Fern Definition isn’t recommended for new customers and Fern isn’t accepting feature requests for this format. It remains supported for existing users.

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:

ValueDescriptionTag
alphaEarly experimental releaseAlpha
in-developmentBeing worked onBeta
betaAvailable but may changeBeta
pre-releaseAvailableBeta
previewFeature-complete but subject to changePreview
generally-availableStable and available for useGA
deprecatedWill be removed in the futureDeprecated
legacySuperseded but still supportedLegacy

Endpoint

pet.yml
service:
  base-path: /pet
  auth: true
  endpoints:
    add:
      availability: deprecated
      display-name: Add pet
      docs: Add a new Pet to the store
      method: POST
      path: ""
      request: AddPetRequest
      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
  Pet:
    properties:
      id: 
        type: integer
        docs: A unique ID for the Pet
      name: 
        type: string
        docs: The first name of the Pet
      photoUrls: 
        type: list<string>
        docs: A list of publicly available URLs featuring the Pet
        availability: generally-available
      category: 
        type: optional<Category>
        availability: pre-release
  Category:
    properties:
      id: optional<integer>
      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
  Pet:
    properties:
      id: 
        type: integer
        docs: A unique ID for the Pet
      name: 
        type: string
        docs: The first name of the Pet
      photoUrls: 
        type: list<string>
        docs: A list of publicly available URLs featuring the Pet
        availability: deprecated
      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, alpha, beta, preview, or legacy.

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
navigation: 
  - api: API Reference
    availability: generally-available
    layout: 
      - section: My Section
        availability: beta
        icon: flower
        contents: 
        # endpoints here