Basic OAS Server Variables Support in API Explorer

Update (Feb 18th, 2022): We’ve since shipped support for enums and you can now manually enter Server Variables via <input>. We’ve updated the content below to reflect this!

OAS 3 introduced the concept of Server Variables. This allows you to configure changeable parts of your API's URL. Here’s an example from the spec:

{
  "servers": [
    {
      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
      "description": "The production API server",
      "variables": {
        "username": {
          "default": "demo",
          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
        },
        "port": {
          "enum": [
            "8443",
            "443"
          ],
          "default": "8443"
        },
        "basePath": {
          "default": "v2"
        }
      }
    }
  ]
}

This tells your API consumers that the {variable} parts in the URL are changeable.

Today we’re introducing support for Server Variables in our API Explorer if you're using JWT Login to get your user data into your docs. For the above example, you would pass the following user object:

{
  name: 'Dom H',
  email: 'dom@readme.io',
  username: 'domh',
  port: 3000,
  basePath: 'custom-base-path'
  version: 1, // Required, if omited things can break unexpectedly
}

This would result in the following URL:

https://domh.gigantic-server.com:3000/custom-base-path

You can see a live demo of this in action over on our demo site:

https://preview.readme.io/?url=server-variables.json

The OAS file backing this example is here.

We're really excited for this feature as it enables you to generate completely custom URLs for each of your customers, while also providing a fallback for those who are not logged in.

This does have some limitations at the moment:

• no enums support now supported
• no top-level input to enter in server variables that are not provided via JWT now supported
• not currently working for Manual APIs defined within ReadMe

If you require these things, let us know by emailing support@readme.io and we can discuss them with you!