Fern 定义高级

Fern Definition 中的可用性

以 Markdown 格式查看

您可以在 Fern Definition 中为端点、类型或属性添加 availability。您可以在 docs.yml 文件中配置 API 参考文档各部分的 availability。

端点、类型和属性

可用性可以是：

  • in-development 表示正在开发中；将显示 Beta 标签
  • pre-release 表示可用；将显示 Beta 标签
  • deprecated 表示将来会被移除；将显示 Deprecated 标签
  • generally-available 表示稳定且可供使用；将显示 GA 标签

端点

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

在 Fern Docs 中，这将显示为：

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

类型

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>

在 Fern Docs 中，这将显示为：

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

属性

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>

在 Fern Docs 中，这将显示为：

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

部分

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
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