extend for definitions for environment variables

[wibed]

environment variables need some way to be defined right?.
ideally some default definition of the same that would outline the scope of the library.

[dfbustosus]

OpenAPI does not currently define process or deployment environment variables. An OpenAPI Description defines the externally observable HTTP interface, so values such as DATABASE_URL, PORT, or LOG_LEVEL normally belong in deployment or application-configuration documentation.

If a value selects the API base URL, use servers or a Server Variable:

servers:
  - url: https://{environment}.example.com/v1
    variables:
      environment:
        default: api
        enum: [api, staging-api]

That is URL-template substitution; it does not tell tooling to read an OS environment variable. If a value is actually sent over HTTP, describe it as a Parameter, Schema field, or Security Scheme as appropriate.

A private machine-readable convention can use a namespaced specification extension such as x-acme-environment-variables, but its schema and behavior would be custom and standard OpenAPI tools would not enforce it. Actual secret values should never be embedded in the document.

If environments expose different contracts, separate descriptions or an OpenAPI Overlay may be clearer. The right representation therefore depends on whether the variable configures the server, a generated library, deployment, or an HTTP request.

References: Server Variables, Specification Extensions, and Overlays.