---
title: "Step 3: The servers object (OpenAPI tutorial)"
date: 2026-10-08
description: "Download PDF In the servers object, you specify the base URL used in your API requests. The base URL is the part of..."
canonical_url: https://idratherbewriting.com/learnapidoc/pubapis_openapi_step3_servers_object
---

> For AI agents: a documentation index is available at https://idratherbewriting.com/llms.txt. Markdown versions of all pages are available by appending .md to any page URL.

# Step 3: The servers object (OpenAPI tutorial)

[STEP 1:openapi object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step1_openapi_object.html)

→

[STEP 2:info object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step2_info_object.html)

→

[STEP 3:servers object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step3_servers_object.html)

→

[STEP 4: paths object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step4_paths_object.html)

→

[STEP 5:components object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step5_components_object.html)

→

[STEP 6:security object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step6_security_object.html)

→

[STEP 7:tags object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step7_tags_object.html)

→

[STEP 8:externalDocs object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step8_externaldocs_object.html)

→

[STEP 9:Other elements](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step9_other_elements.html)

[Download PDF](https://www.buymeacoffee.com/learnapidoc/e/146076)

In the [`servers` object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.1.md#serverObject), you specify the base URL used in your API requests. The base URL is the part of the URL that appears before the endpoint path.

## Sample servers object

The following is a sample `servers` object:

```yaml
servers:
- url: https://api.openweathermap.org/data/2.5
```

Each of your endpoints (called “paths” in the spec) will be appended to the server URL to construct the full request URL. For example, if one of the paths is `/weather`, when Swagger UI submits the request, it will submit it to `{server URL}{path}` which resolves to `https://api.openweathermap.org/data/2.5/weather`.

## Options with the server URL

You have some flexibility and configuration options for your server URL. You can specify multiple server URLs that might relate to different environments (test, beta, production). If you have multiple server URLs, users can select the environment from a servers drop-down box. For example, you can specify multiple server URLs like this:

```yaml
servers:
- url: https://api.openweathermap.org/data/2.5
  description: Production server
- url: http://beta.api.openweathermap.org/data/2.5
  description: Beta server
- url: http://some-other.api.openweathermap.org/data/2.5
  description: Some other server
```

If you get stuck, see the [sample OpenAPI spec here](https://idratherbewriting.com/docs/openapi_spec_and_generated_ref_docs/openapi_openweathermap.yml) for the fully working sample. This will help you spot and troubleshoot indentation or other errors.

In Swagger UI, the multiple servers appear as options users can select in a drop-down list:

[![](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/api/openapi_serversurl.png)](https://idratherbewriting.com/assets/files/swagger/index.html)

If you have just one URL, you still see a drop-down box but with just one option.

You can also incorporate variables into the server URL that can be populated at runtime by your server. Additionally, if different paths (endpoints) require different server URLs, you can add the `servers` object as a property in the [`path`](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step4_paths_object.html) object’s operation object. The locally declared servers URL will override the global servers URL.

See [“Overriding Servers”](https://swagger.io/docs/specification/api-host-and-base-path/) in “API Server and Base URL” (Swagger’s docs) for more details.

## Swagger

Paste the `servers` object (the [first code sample above](#sample_servers_object) showing just one `url`) into your Swagger Editor, adding to the code you already have there. Swagger UI will look as follows.

![Swagger UI with the servers object](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/api/swagger_servers_object2.png)

Notice the drop-down menu that appears in the lower-right. (Even if you have just one URL, it still appears in a drop-down menu.)