Fern Definition 中的包

什么是包？

API 定义中的每个文件夹都是一个包。

生成的 SDK 将匹配你的 API 定义的层次结构。

1
const client = new Client();
2
3
// 调用在 projects.yml 中定义的端点
4
client.projects.get();
5
6
// 调用在 roles/admin.yml 中定义的端点
7
client.roles.admin.get();

包配置

每个包可以有一个名为 __package__.yml 的特殊定义文件。与任何其他定义文件一样，它可以包含导入、类型、端点和错误。

__package__.yml 中的端点将出现在包的根目录。 例如，以下生成的 SDK：

1
const client = new Client();
2
3
client.getProjects();

将有一个 fern/ 文件夹：

其中包含以下 __package__.yml：

1
service:
2
  base-path: ""
3
  auth: false
4
  endpoints:
5
    getProjects:
6
      method: GET
7
      path: ""
8
      response: list<Project>

命名空间

每个包都有自己的命名空间。这意味着你可以在不同包中重用类型名称和错误名称。

这在对 API 进行版本控制时很有用。例如，当你想要增加 API 版本时，可以将现有 API 复制到新包中并开始进行更改。如果新的 API 版本重用了某些类型或错误，这是可以的，因为两个 API 存在于不同的包中。

导航

__package__.yml 还允许你配置服务的导航顺序。当你想要控制文档的显示时，这很有用。

例如，假设你有以下 fern/ 文件夹：

你的 API 将按字母顺序排序：projects、roles，然后是 users。如果你想要控制导航，可以添加一个 __package__.yml 文件并配置顺序：

1
navigation: 
2
  - users.yml
3
  - roles.yml
4
  - projects.yml