{"id":3001,"date":"2025-01-07T20:16:28","date_gmt":"2025-01-08T02:16:28","guid":{"rendered":"https:\/\/readme.com\/resources\/?p=3001"},"modified":"2025-01-07T20:16:29","modified_gmt":"2025-01-08T02:16:29","slug":"basic-oas-server-variables-support","status":"publish","type":"post","link":"https:\/\/readme.com\/resources\/basic-oas-server-variables-support","title":{"rendered":"Basic OAS Server Variables Support in API Explorer"},"content":{"rendered":"\n
\n

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

OAS 3 introduced the concept of Server Variables<\/a>. This allows you to configure changeable parts of your API’s URL. Here\u2019s an example from the spec:<\/p>\n\n\n\n

{\n  \"servers\": [\n    {\n      \"url\": \"https:\/\/{username}.gigantic-server.com:{port}\/{basePath}\",\n      \"description\": \"The production API server\",\n      \"variables\": {\n        \"username\": {\n          \"default\": \"demo\",\n          \"description\": \"this value is assigned by the service provider, in this example `gigantic-server.com`\"\n        },\n        \"port\": {\n          \"enum\": [\n            \"8443\",\n            \"443\"\n          ],\n          \"default\": \"8443\"\n        },\n        \"basePath\": {\n          \"default\": \"v2\"\n        }\n      }\n    }\n  ]\n}\n<\/code><\/pre>\n\n\n\n
This tells your API consumers that the {variable}<\/code> parts in the URL are changeable.<\/p>\n\n\n\n
Today we\u2019re introducing support for Server Variables in our API Explorer<\/a> if you’re using JWT Login<\/a> to get your user data into your docs. For the above example, you would pass the following user object:<\/p>\n\n\n\n
{\n  name: 'Dom H',\n  email: 'dom@readme.io',\n  username: 'domh',\n  port: 3000,\n  basePath: 'custom-base-path'\n  version: 1, \/\/ Required, if omited things can break unexpectedly\n}\n<\/code><\/pre>\n\n\n\n
This would result in the following URL:<\/p>\n\n\n\n
\nhttps:\/\/domh.gigantic-server.com:3000\/custom-base-path\n<\/div><\/figure>\n\n\n\n
You can see a live demo of this in action over on our demo site:<\/p>\n\n\n\n
\nhttps:\/\/preview.readme.io\/?url=server-variables.json\n<\/div><\/figure>\n\n\n\n
The OAS file backing this example is here<\/a>.<\/p>\n\n\n\n
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.<\/p>\n\n\n\n
This does have some limitations at the moment:<\/p>\n\n\n\n