OpenAPI 3.0中服务器属性的重要性是什么?

问题描述

在 OpenAPI 3.0规范中，根 OpenAPI对象具有servers属性，该属性是服务器对象.并且路径项对象允许一个可选的servers属性.

In the OpenAPI 3.0 Specification, the root OpenAPI Object has the servers property which is an array of Server Objects. And the Path Item Object also allows an optional servers property.

《规范》中的描述并未明确说明servers的帮助方式.

The description given in the Specification does not give a clear idea of how servers can be helpful.

servers属性的意义是什么?我们是否有任何示例将servers的用例既解释为根OpenAPI对象的直接属性，又解释为路径项的属性?

What is the significance of the servers property? Do we have any example which explains the use cases of servers both as a direct property of the root OpenAPI object and also as a property of a path item?

推荐答案

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

servers specifies one or more target servers for the API, in other words, the base URL for API calls. The endpoint paths (e.g. /users/{id}) are defined relative to these servers. Some APIs have a single target server; others may offer several servers, e.g. sandbox vs. production, or regional servers for different geographical areas (example: AWS).

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

By default, all operations in an OpenAPI definition use the globally defined servers, but servers may also be overridden for specific paths and operations. This is useful for APIs where some operations use a different server than the rest of the operations. This way you can document all operations in a single API definition instead of splitting it into multiple definitions, one per server.

示例: Dropbox API

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

• Most endpoints are on the api.dropboxapi.com domain.
• Content upload/download endpoints are on content.dropboxapi.com.
• Longpoll endpoint is on notify.dropboxapi.com.
• OAuth endpoints are on www.dropbox.com.

Dropbox API定义可能如下所示:

The Dropbox API definition might look like this:

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主机和基本路径指南以了解更多信息详细信息和示例.

Check out the API Host and Base Path guide for more details and examples.

这篇关于OpenAPI 3.0中服务器属性的重要性是什么?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！