OAI / OAI/Overlay-Specification

Environment Variables in definition

Open
#33 15 comments 13 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
121
Forks
38
Avg merge
53m
Merged PRs (30d)
6

Description

Sorry if this came up before, I searched but could not find anything.

Environment variables have become something of the de facto mechanism to set server-specific values, then access them from software. The hosting providers I have worked with (AWS, Heroku, OpenShift) all offer features to easily set/import/export them and most software I've seen meant to run on these systems uses it for things like environment specific URLs, secrets etc.

But afaik there is no way to reference environment variables in an OpenAPI definition.

Would this be a feature to support? I imagine the definition having a section (probably at the top level) that specified a set of environment variables expected to be set, and possibly the default values to use when they are not set. Those variables could then be used in other parts of the definition.

My practical use cases comes from needing to set different authorization urls for different environments. Currently I am rendering swagger.json from JSP to implement this myself, but it seems to me this is a very generic use case that many people will face.

See also e.g.
https://github.com/OAI/OpenAPI-Specification/issues/169
https://github.com/OAI/OpenAPI-Specification/issues/779
https://github.com/swagger-api/swagger-ui/pull/3410

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No implementation files or tests are named. Start by reading the discussion, the linked OpenAPI issues, and the Swagger UI pull request to understand the intended scope. Done requires an agreed, implementable environment-variable model for definitions, including how values are declared and referenced.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi
Domain
api
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.