服务器属性在OpenAPI 3.0中的意义是什么?

Question

在OpenAPI 3.0规范中，根OpenAPI对象具有servers属性，该属性是服务器对象的数组。路径项对象还允许可选的servers属性。

规范中给出的描述并没有清楚地说明servers如何提供帮助。

servers属性的意义是什么？我们是否有任何示例来解释servers作为根 OpenAPI 对象的直接属性和路径项的属性的用例？

Answer 1

servers指定 API 的一个或多个目标服务器，换句话说，API 调用的基本 URL。端点路径(例如/users/{id}( 是相对于这些服务器定义的。某些 API 具有单个目标服务器;其他人可能提供多台服务器，例如沙盒与生产服务器，或针对不同地理区域的区域服务器(例如：AWS(。

默认情况下，OpenAPI 定义中的所有操作都使用全局定义的servers，但对于特定路径和操作，servers也可能被覆盖。这对于某些操作使用与其他操作不同的服务器的 API 非常有用。这样，您可以在单个 API 定义中记录所有操作，而不是将其拆分为多个定义，每个服务器一个。

示例：Dropbox API

• 大多数终结点位于api.dropboxapi.com域中。
• 内容上传/下载端点位于content.dropboxapi.com上。
• Longpoll 端点在notify.dropboxapi.com上
。
• OAuth 端点位于www.dropbox.com上。

Dropbox API 定义可能如下所示：

openapi: 3.0.0
info:
title: Dropbox API
version: 1.0.0
servers:
- url: 'https://api.dropboxapi.com/2'
paths:
# These endpoints are on api.dropboxapi.com (use global `servers`)
/file_requests/list:
...
/users/get_account:
...
/files/upload:
# File upload/download uses another target server
servers:
- url: 'https://content.dropboxapi.com/2'
...
/files/list_folder/longpoll:
# Longpolling uses another target server
servers:
- url: 'https://notify.dropboxapi.com/2'
...

有关更多详细信息和示例，请查看 API 主机和基本路径指南。