Fern Definition 中的端点

在 Fern 中，您将相关端点组织成一个 Service（服务）。这种分组提高了清晰度，并使生成的 SDK 更加地道。

服务定义

每个服务定义：

base-path（基础路径）：所有端点 HTTP 路径的通用前缀
服务是否需要身份验证
Endpoints（端点）

user.yml

1   service: 
2     base-path: /users # 这定义了方法的组/命名空间
3     auth: false 
4     endpoints: {}

要定义具有空基础路径的服务，请使用空字符串：base-path: ""

节显示名称

默认情况下，API 参考中的节名称来自服务文件名（例如，user.yml 变成”User”）。要覆盖节的显示名称，在您的 docs.yml 中使用 section 属性。

SDK 方法名称

SDK 方法名称直接从服务文件名和端点键派生。文件名成为命名空间，端点键成为方法名。

例如，给定以下定义：

users.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     create:
6       path: ""
7       method: POST
8       request: CreateUserRequest

Fern 生成一个名为 client.users.create() 的方法。

端点

端点包括：

URL 路径 （可选择包含路径参数）
显示名称 （可选）
HTTP 方法
请求信息 （可选）
- Query-parameters（查询参数）
- Headers（请求头）
- Request body（请求体）
成功（200）响应信息 （可选）
此端点可能返回的错误（非 200）响应 （可选）

URL 路径

每个端点都有一个 URL 路径。

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     getAllUsers:
6       path: /all
7       method: GET

端点的完整路径是以下内容的连接：

环境 URL
服务 base-path
端点 path

端点显示名称

显示名称将作为端点的标题出现。默认情况下，显示名称等于端点名称的”标题大小写”。如果您想要自定义端点名称，可以设置显示名称。

在下面的示例中，“Add a new plant to the store” 作为 API 参考中端点页面的标题显示。

user.yml

1 service:
2   base-path: /v3
3   auth: false
4   endpoints:
5     addPlant:
6       path: /plant
7       display-name: Add a new plant to the store
8       method: POST

路径参数

为您的端点提供路径参数以创建动态 URL。

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     getUser:
6       path: /{userId} 
7       path-parameters: 
8         userId: string
9       method: GET

服务也可以有路径参数：

project.yml

1 service: 
2   base-path: /projects/{projectId}
3   path-parameters: 
4     projectId: string 
5   auth: false 
6   endpoints: 
7     ...

查询参数

每个端点可以指定查询参数：

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     getAllUsers:
6       path: /all
7       method: GET
8       request:
9         # 这个名称对于地道的 SDK 是必需的
10         name: GetAllUsersRequest
11         query-parameters:
12           limit: optional<integer>

`allow-multiple`

使用 allow-multiple 指定查询参数在 URL 中允许多次出现，如 ?filter=jane&filter=smith。这将改变生成的 SDK，使消费者可以为查询参数提供多个值。

user.yml

1   ...
2   query-parameters:
3     filter:
4       type: string
5       allow-multiple: true

认证

每个端点都可以覆盖服务中指定的认证行为。

user.yml

1 service: 
2   base-path: /users 
3   auth: false 
4   endpoints: 
5     getMe: 
6       path: "" 
7       method: GET 
8       # 此端点将进行认证
9       auth: true 
10       docs: 基于 Authorization 头返回当前用户。

请求头

每个端点可以指定请求头：

user.yml

1 service: 
2   base-path: /users 
3   auth: false 
4   endpoints: 
5     getAllUsers: 
6       path: /all
7       method: GET 
8       request: 
9         # 这个名称对于地道的 SDK 是必需的
10         name: GetAllUsersRequest 
11         headers: 
12           X-Endpoint-Header: string

服务也可以指定请求头。这些头将级联到服务的端点。

user.yml

1 service: 
2   base-path: /users 
3   auth: false 
4   headers: 
5     X-Service-Header: string 
6   endpoints: 
7     getAllUsers: 
8       path: /all 
9       method: GET 
10       request: 
11         # 这个名称对于地道的 SDK 是必需的
12         name: GetAllUsersRequest 
13         headers: 
14           X-Endpoint-Header: string

请求体

端点可以指定请求体类型。

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     setUserName:
6       path: /{userId}/set-name
7       path-parameters:
8         userId: string
9       method: POST
10       request: string

内联请求体

如果请求体是一个对象，您可以内联类型声明。这使生成的 SDK 更加地道。

user.yml

1 service: 
2   base-path: /users 
3   auth: false 
4   endpoints: 
5     createUser: 
6       path: /create 
7       method: POST 
8       request: 
9         # 这个名称对于地道的 SDK 是必需的
10         name: CreateUserRequest 
11         body: 
12           properties: 
13             userName: string

成功响应

端点可以指定 response，这是在成功（200）调用时返回的主体类型。

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     getAllUsers:
6       path: /all
7       method: GET
8       response: list<User>
9 
10 types:
11   User:
12     properties:
13       userId: string
14       name: string

响应状态码

您还可以使用 status-code 字段为成功响应指定自定义状态码。

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     create: :
6       path: ""
7       method: POST
8       request: CreateUserRequest
9       response: 
10         type: User
11         status-code: 201
12 
13 types:
14   User:
15     properties:
16       userId: string
17       name: string

分页

Fern 支持偏移、游标、URI 和基于路径的分页方案。要在生成的 SDK 中设置自动分页：

使用 pagination 字段标注所需的分页端点
指定分页方案（offset、cursor、next_uri 或 next_path）
使用点访问表示法指定 results 的位置。

偏移分页选项

在大多数偏移分页配置中包含 step，以确保偏移按页面大小递增。当您的 API 返回附加页面的布尔指示器时，请使用 has-next-page。

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     list:
6       path: ""
7       method: GET
8       pagination:
9         offset: $request.page
10         step: $request.page_size # 推荐
11         results: $response.data
12         has-next-page: $response.has_more
13       request:
14         name: ListUsersRequest
15         query-parameters:
16           page: optional<integer>
17           page_size: optional<integer>
18       response: ListUsersResponse
19 
20 types:
21   ListUsersResponse:
22     properties:
23       data: list<User>
24       has_more: boolean

pagination 字段支持以下属性：

Property	Description
`offset`	Path to the offset parameter in the request (e.g., `$request.page`)
`cursor`	Path to the cursor parameter in the request (e.g., `$request.cursor`)
`next_cursor`	Path to the next cursor value in the response (required for cursor pagination)
`next_uri`	Path to the next page’s URL in the response (e.g., `$response.next_page_url`)
`next_path`	Path to the relative path for the next page in the response (e.g., `$response.next_page_path`)
`results`	Path to the results array in the response (e.g., `$response.data`)
`step`	Path to the page size parameter, ensures offset increments correctly
`has-next-page`	Path to a boolean indicator for additional pages

幂等端点

将端点标记为幂等，以允许 SDK 用户为安全请求重试指定幂等性头。您还必须在 api.yml 中配置幂等性头来定义哪些头可用。

service.yml

1 service:
2   base-path: /transactions
3   auth: true
4   endpoints:
5     send:
6       path: ""
7       method: POST
8       idempotent: true
9       request: SendTransactionRequest
10       response: Transaction

错误响应

端点可以指定错误响应，详细说明端点可能返回的非 200 响应。

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     getUser:
6       path: /{userId}
7       path-parameters:
8         userId: string
9       method: GET
10       response: User
11       errors:
12         - UserNotFoundError
13 
14 types:
15   User:
16     properties:
17       userId: string
18       name: string
19 
20 errors:
21   UserNotFoundError:
22     status-code: 404

您可以在错误页面了解更多关于如何定义错误的信息。

指定示例

当您声明一个示例时，您还可以指定一些该端点如何使用的示例。这些被编译器用来增强生成的输出。示例将在您的 SDK、API 文档和 Postman 集合中显示为注释。

您可以为端点、类型和错误添加示例。

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     getUser:
6       path: /{userId}
7       path-parameters:
8         userId: string
9       method: GET
10       response: User
11       errors:
12         - UserNotFoundError
13       examples:
14         - path-parameters:
15             userId: alice-user-id
16           response:
17             body:
18               userId: alice-user-id
19               name: Alice
20 
21 types:
22   User:
23     properties:
24       userId: string
25       name: string
26 
27 errors:
28   UserNotFoundError:
29     status-code: 404

如果您要向端点添加示例且类型已经有示例，您可以使用 $ 引用它。

1 service:
2   auth: true
3   base-path: /address
4   endpoints:
5     create:
6       method: POST
7       path: ""
8       request: CreateAddress
9       response: Address
10       examples:
11         - request: $CreateAddress.WhiteHouse
12           response:
13             body: $Address.WhiteHouseWithID
14 
15   CreateAddress:
16     properties:
17       street1: string
18       street2: optional<string>
19       city: string
20       state: string
21       postalCode: string
22       country: string
23       isResidential: boolean
24     examples:
25       - name: WhiteHouse
26         value:
27           street1: 1600 Pennsylvania Avenue NW
28           city: Washington DC
29           state: Washington DC
30           postalCode: "20500"
31           country: US
32           isResidential: true
33 
34   Address:
35     extends: CreateAddress
36     properties:
37       id:
38         type: uuid
39         docs: 地址的唯一标识符。
40     examples:
41       - name: WhiteHouseWithID
42         value:
43           id: 65ce514c-41e3-11ee-be56-0242ac120002
44           street1: 1600 Pennsylvania Avenue NW
45           city: Washington DC
46           state: Washington DC
47           postalCode: "20500"
48           country: US
49           isResidential: true

示例包含有关端点调用的所有信息，包括请求体、路径参数、查询参数、头和响应体。

user.yml

1 examples: 
2   - path-parameters: 
3       userId: some-user-id 
4     query-parameters:
5       limit: 50 
6     headers: 
7       X-My-Header: some-value 
8     response: 
9       body: 
10         response-field: hello

失败示例

您还可以指定失败端点调用的示例。添加 error 属性到响应示例以指定您正在演示哪个失败。

user.yml

1 examples:
2   - path-parameters:
3       userId: missing-user-id
4     response:
5       error: UserNotFoundError
6 
7 errors:
8   UserNotFoundError:
9     status-code: 404

如果错误有主体，则必须在示例中包含主体。

user.yml

1 examples:
2   - path-parameters:
3       userId: missing-user-id
4     response:
5       error: UserNotFoundError
6       body: "User with id `missing-user-id` was not found"
7 
8 errors:
9   UserNotFoundError:
10     status-code: 404
11     type: string

从类型引用示例

为避免重复，您可以使用 $ 从类型引用示例。

user.yml

1 service:
2   base-path: /users
3   auth: true
4   endpoints:
5     getUser:
6       method: GET
7       path: /{userId}
8       path-parameters:
9         userId: UserId
10       examples:
11         - path-parameters:
12             userId: $UserId.Example1
13 
14 types:
15   UserId:
16   type: integer
17   examples: 
18     - name: Example1
19       value: user-id-123

在 Fern 中，您将相关端点组织成一个 Service（服务）。这种分组提高了清晰度，并使生成的 SDK 更加地道。

服务定义

每个服务定义：

base-path（基础路径）：所有端点 HTTP 路径的通用前缀
服务是否需要身份验证
Endpoints（端点）

user.yml

1   service: 
2     base-path: /users # 这定义了方法的组/命名空间
3     auth: false 
4     endpoints: {}

要定义具有空基础路径的服务，请使用空字符串：base-path: ""

节显示名称

默认情况下，API 参考中的节名称来自服务文件名（例如，user.yml 变成”User”）。要覆盖节的显示名称，在您的 docs.yml 中使用 section 属性。

SDK 方法名称

SDK 方法名称直接从服务文件名和端点键派生。文件名成为命名空间，端点键成为方法名。

例如，给定以下定义：

users.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     create:
6       path: ""
7       method: POST
8       request: CreateUserRequest

Fern 生成一个名为 client.users.create() 的方法。

端点

端点包括：

URL 路径 （可选择包含路径参数）
显示名称 （可选）
HTTP 方法
请求信息 （可选）
- Query-parameters（查询参数）
- Headers（请求头）
- Request body（请求体）
成功（200）响应信息 （可选）
此端点可能返回的错误（非 200）响应 （可选）

URL 路径

每个端点都有一个 URL 路径。

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     getAllUsers:
6       path: /all
7       method: GET

端点的完整路径是以下内容的连接：

环境 URL
服务 base-path
端点 path

端点显示名称

显示名称将作为端点的标题出现。默认情况下，显示名称等于端点名称的”标题大小写”。如果您想要自定义端点名称，可以设置显示名称。

在下面的示例中，“Add a new plant to the store” 作为 API 参考中端点页面的标题显示。

user.yml

1 service:
2   base-path: /v3
3   auth: false
4   endpoints:
5     addPlant:
6       path: /plant
7       display-name: Add a new plant to the store
8       method: POST

路径参数

为您的端点提供路径参数以创建动态 URL。

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     getUser:
6       path: /{userId} 
7       path-parameters: 
8         userId: string
9       method: GET

服务也可以有路径参数：

project.yml

1 service: 
2   base-path: /projects/{projectId}
3   path-parameters: 
4     projectId: string 
5   auth: false 
6   endpoints: 
7     ...

查询参数

每个端点可以指定查询参数：

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     getAllUsers:
6       path: /all
7       method: GET
8       request:
9         # 这个名称对于地道的 SDK 是必需的
10         name: GetAllUsersRequest
11         query-parameters:
12           limit: optional<integer>

`allow-multiple`

使用 allow-multiple 指定查询参数在 URL 中允许多次出现，如 ?filter=jane&filter=smith。这将改变生成的 SDK，使消费者可以为查询参数提供多个值。

user.yml

1   ...
2   query-parameters:
3     filter:
4       type: string
5       allow-multiple: true

认证

每个端点都可以覆盖服务中指定的认证行为。

user.yml

1 service: 
2   base-path: /users 
3   auth: false 
4   endpoints: 
5     getMe: 
6       path: "" 
7       method: GET 
8       # 此端点将进行认证
9       auth: true 
10       docs: 基于 Authorization 头返回当前用户。

请求头

每个端点可以指定请求头：

user.yml

1 service: 
2   base-path: /users 
3   auth: false 
4   endpoints: 
5     getAllUsers: 
6       path: /all
7       method: GET 
8       request: 
9         # 这个名称对于地道的 SDK 是必需的
10         name: GetAllUsersRequest 
11         headers: 
12           X-Endpoint-Header: string

服务也可以指定请求头。这些头将级联到服务的端点。

user.yml

1 service: 
2   base-path: /users 
3   auth: false 
4   headers: 
5     X-Service-Header: string 
6   endpoints: 
7     getAllUsers: 
8       path: /all 
9       method: GET 
10       request: 
11         # 这个名称对于地道的 SDK 是必需的
12         name: GetAllUsersRequest 
13         headers: 
14           X-Endpoint-Header: string

请求体

端点可以指定请求体类型。

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     setUserName:
6       path: /{userId}/set-name
7       path-parameters:
8         userId: string
9       method: POST
10       request: string

内联请求体

如果请求体是一个对象，您可以内联类型声明。这使生成的 SDK 更加地道。

user.yml

1 service: 
2   base-path: /users 
3   auth: false 
4   endpoints: 
5     createUser: 
6       path: /create 
7       method: POST 
8       request: 
9         # 这个名称对于地道的 SDK 是必需的
10         name: CreateUserRequest 
11         body: 
12           properties: 
13             userName: string

成功响应

端点可以指定 response，这是在成功（200）调用时返回的主体类型。

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     getAllUsers:
6       path: /all
7       method: GET
8       response: list<User>
9 
10 types:
11   User:
12     properties:
13       userId: string
14       name: string

响应状态码

您还可以使用 status-code 字段为成功响应指定自定义状态码。

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     create: :
6       path: ""
7       method: POST
8       request: CreateUserRequest
9       response: 
10         type: User
11         status-code: 201
12 
13 types:
14   User:
15     properties:
16       userId: string
17       name: string

分页

Fern 支持偏移、游标、URI 和基于路径的分页方案。要在生成的 SDK 中设置自动分页：

使用 pagination 字段标注所需的分页端点
指定分页方案（offset、cursor、next_uri 或 next_path）
使用点访问表示法指定 results 的位置。

偏移分页选项

在大多数偏移分页配置中包含 step，以确保偏移按页面大小递增。当您的 API 返回附加页面的布尔指示器时，请使用 has-next-page。

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     list:
6       path: ""
7       method: GET
8       pagination:
9         offset: $request.page
10         step: $request.page_size # 推荐
11         results: $response.data
12         has-next-page: $response.has_more
13       request:
14         name: ListUsersRequest
15         query-parameters:
16           page: optional<integer>
17           page_size: optional<integer>
18       response: ListUsersResponse
19 
20 types:
21   ListUsersResponse:
22     properties:
23       data: list<User>
24       has_more: boolean

pagination 字段支持以下属性：

Property	Description
`offset`	Path to the offset parameter in the request (e.g., `$request.page`)
`cursor`	Path to the cursor parameter in the request (e.g., `$request.cursor`)
`next_cursor`	Path to the next cursor value in the response (required for cursor pagination)
`next_uri`	Path to the next page’s URL in the response (e.g., `$response.next_page_url`)
`next_path`	Path to the relative path for the next page in the response (e.g., `$response.next_page_path`)
`results`	Path to the results array in the response (e.g., `$response.data`)
`step`	Path to the page size parameter, ensures offset increments correctly
`has-next-page`	Path to a boolean indicator for additional pages

幂等端点

将端点标记为幂等，以允许 SDK 用户为安全请求重试指定幂等性头。您还必须在 api.yml 中配置幂等性头来定义哪些头可用。

service.yml

1 service:
2   base-path: /transactions
3   auth: true
4   endpoints:
5     send:
6       path: ""
7       method: POST
8       idempotent: true
9       request: SendTransactionRequest
10       response: Transaction

错误响应

端点可以指定错误响应，详细说明端点可能返回的非 200 响应。

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     getUser:
6       path: /{userId}
7       path-parameters:
8         userId: string
9       method: GET
10       response: User
11       errors:
12         - UserNotFoundError
13 
14 types:
15   User:
16     properties:
17       userId: string
18       name: string
19 
20 errors:
21   UserNotFoundError:
22     status-code: 404

您可以在错误页面了解更多关于如何定义错误的信息。

指定示例

您可以为端点、类型和错误添加示例。

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     getUser:
6       path: /{userId}
7       path-parameters:
8         userId: string
9       method: GET
10       response: User
11       errors:
12         - UserNotFoundError
13       examples:
14         - path-parameters:
15             userId: alice-user-id
16           response:
17             body:
18               userId: alice-user-id
19               name: Alice
20 
21 types:
22   User:
23     properties:
24       userId: string
25       name: string
26 
27 errors:
28   UserNotFoundError:
29     status-code: 404

如果您要向端点添加示例且类型已经有示例，您可以使用 $ 引用它。

1 service:
2   auth: true
3   base-path: /address
4   endpoints:
5     create:
6       method: POST
7       path: ""
8       request: CreateAddress
9       response: Address
10       examples:
11         - request: $CreateAddress.WhiteHouse
12           response:
13             body: $Address.WhiteHouseWithID
14 
15   CreateAddress:
16     properties:
17       street1: string
18       street2: optional<string>
19       city: string
20       state: string
21       postalCode: string
22       country: string
23       isResidential: boolean
24     examples:
25       - name: WhiteHouse
26         value:
27           street1: 1600 Pennsylvania Avenue NW
28           city: Washington DC
29           state: Washington DC
30           postalCode: "20500"
31           country: US
32           isResidential: true
33 
34   Address:
35     extends: CreateAddress
36     properties:
37       id:
38         type: uuid
39         docs: 地址的唯一标识符。
40     examples:
41       - name: WhiteHouseWithID
42         value:
43           id: 65ce514c-41e3-11ee-be56-0242ac120002
44           street1: 1600 Pennsylvania Avenue NW
45           city: Washington DC
46           state: Washington DC
47           postalCode: "20500"
48           country: US
49           isResidential: true

示例包含有关端点调用的所有信息，包括请求体、路径参数、查询参数、头和响应体。

user.yml

1 examples: 
2   - path-parameters: 
3       userId: some-user-id 
4     query-parameters:
5       limit: 50 
6     headers: 
7       X-My-Header: some-value 
8     response: 
9       body: 
10         response-field: hello

失败示例

您还可以指定失败端点调用的示例。添加 error 属性到响应示例以指定您正在演示哪个失败。

user.yml

1 examples:
2   - path-parameters:
3       userId: missing-user-id
4     response:
5       error: UserNotFoundError
6 
7 errors:
8   UserNotFoundError:
9     status-code: 404

如果错误有主体，则必须在示例中包含主体。

user.yml

1 examples:
2   - path-parameters:
3       userId: missing-user-id
4     response:
5       error: UserNotFoundError
6       body: "User with id `missing-user-id` was not found"
7 
8 errors:
9   UserNotFoundError:
10     status-code: 404
11     type: string

从类型引用示例

为避免重复，您可以使用 $ 从类型引用示例。

user.yml

1 service:
2   base-path: /users
3   auth: true
4   endpoints:
5     getUser:
6       method: GET
7       path: /{userId}
8       path-parameters:
9         userId: UserId
10       examples:
11         - path-parameters:
12             userId: $UserId.Example1
13 
14 types:
15   UserId:
16   type: integer
17   examples: 
18     - name: Example1
19       value: user-id-123

1	service:
2	base-path: /users # 这定义了方法的组/命名空间
3	auth: false
4	endpoints: {}

1	service:
2	base-path: /users
3	auth: false
4	endpoints:
5	create:
6	path: ""
7	method: POST
8	request: CreateUserRequest

1	service:
2	base-path: /v3
3	auth: false
4	endpoints:
5	addPlant:
6	path: /plant
7	display-name: Add a new plant to the store
8	method: POST

1	service:
2	base-path: /projects/{projectId}
3	path-parameters:
4	projectId: string
5	auth: false
6	endpoints:
7	...

1	...
2	query-parameters:
3	filter:
4	type: string
5	allow-multiple: true

1	service:
2	base-path: /transactions
3	auth: true
4	endpoints:
5	send:
6	path: ""
7	method: POST
8	idempotent: true
9	request: SendTransactionRequest
10	response: Transaction

1	service:
2	auth: true
3	base-path: /address
4	endpoints:
5	create:
6	method: POST
7	path: ""
8	request: CreateAddress
9	response: Address
10	examples:
11	- request: $CreateAddress.WhiteHouse
12	response:
13	body: $Address.WhiteHouseWithID
14
15	CreateAddress:
16	properties:
17	street1: string
18	street2: optional<string>
19	city: string
20	state: string
21	postalCode: string
22	country: string
23	isResidential: boolean
24	examples:
25	- name: WhiteHouse
26	value:
27	street1: 1600 Pennsylvania Avenue NW
28	city: Washington DC
29	state: Washington DC
30	postalCode: "20500"
31	country: US
32	isResidential: true
33
34	Address:
35	extends: CreateAddress
36	properties:
37	id:
38	type: uuid
39	docs: 地址的唯一标识符。
40	examples:
41	- name: WhiteHouseWithID
42	value:
43	id: 65ce514c-41e3-11ee-be56-0242ac120002
44	street1: 1600 Pennsylvania Avenue NW
45	city: Washington DC
46	state: Washington DC
47	postalCode: "20500"
48	country: US
49	isResidential: true

1	examples:
2	- path-parameters:
3	userId: some-user-id
4	query-parameters:
5	limit: 50
6	headers:
7	X-My-Header: some-value
8	response:
9	body:
10	response-field: hello

1	examples:
2	- path-parameters:
3	userId: missing-user-id
4	response:
5	error: UserNotFoundError
6
7	errors:
8	UserNotFoundError:
9	status-code: 404