What is the significance of servers property in OpenAPI 3.0?

Question

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.

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

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?

Answer 1

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

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.

Example: Dropbox API

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

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

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