Skip to main content

openapi server

openapi server

The openapi server binding creates composite of tcp, tls, and http bindings with server kind and adapts HTTP request-response streams to OpenAPI request-response streams.

openapi_server:
  type: openapi
  kind: server
  options:
    specs:
      petstore:
        servers:
          - http://localhost:9090
        catalog:
          my_catalog:
            subject: petstore
            version: latest
  exit: openapi_client

Configuration (* required)

vault

string

Vault name.

options

object

The openapi specific options.

options:
    specs:
      petstore:
        servers:
          - http://localhost:9090
        catalog:
          my_catalog:
            subject: petstore
            version: latest

options.specs

object as map of named object properties

The specs specific options.

specs.servers*

array of string

Deployment-target URLs for the spec, independent of the servers declared in the spec document itself. At least one is required.

specs:
  petstore:
    servers:
      - http://backend.internal:9090

specs.security

object as map of named string properties, at most one entry

Maps an OpenAPI securitySchemes name declared in the spec document to a guard defined elsewhere in the configuration. Used to automatically derive guarded: on the routes generated for the composite, and to synthesize the matching credential-extraction pattern for the generated http binding from the scheme's own declared type — an http/bearer scheme extracts an Authorization: Bearer {credentials} header; an apiKey scheme extracts from whichever header, query, or cookie location and parameter name the scheme declares. No separate authorization configuration is needed.

specs:
  petstore:
    security:
      bearerAuth: my_jwt_guard

specs.catalog

object as map of named object properties

The catalog specific options.

catalog.subject*

string

Subject name used when storing the catalog artifact.

catalog.version

string | Default: latest

Catalog artifact version to use.

specs.overlay

object as map of named object properties

Applies an OpenAPI Overlay Specification document, stored as a catalog artifact, to the base spec document before it is used. A single overlay may be configured per spec.

specs:
  petstore:
    catalog:
      my_catalog:
        subject: petstore
        version: latest
    overlay:
      my_catalog:
        subject: petstore-overlay
        version: latest

overlay.subject*

string

Subject name used when storing the overlay artifact.

overlay.version

string | Default: latest

Overlay artifact version to use.

For each https server, a tls binding is generated automatically, with keys, trust, signers, and SNI resolved from vault and ALPN computed automatically — no separate TLS options are configured on this binding.

routes

array of object

Conditional openapi specific routes, available for kind: server only.

routes:
  - when:
      - tag: pets
    exit: pets_backend

routes[].guarded

object as map of named array of string

List of roles required by each named guard to authorize this route.

routes:
  - guarded:
      my_guard:
        - read:items

routes[].when

array of object

List of conditions to match this route. Read more: When a route matches

when[].spec

string

OpenAPI spec label that matches the resolved specification for the request.

when[].operation

string

OpenAPI operationId to match, either exactly or as a glob pattern, e.g. list*.

when[].tag

string

Matches when the resolved operation declares this tag.

when[].servers

array of object

Matches when the resolved server for the request is one of these servers.

servers[].url

string

Server url to match.

routes[].exit

string

Next binding when following this route.

routes:
  - when:
      ...
    exit: openapi_client

exit

string

Default exit binding when no conditional routes are viable.

exit: echo_server

telemetry

object

Defines the desired telemetry for the binding.

telemetry.metrics

array

Telemetry metrics to track

telemetry:
  metrics:
    - stream.*

telemetry.attributes

object as map of named string properties

Telemetry attributes to add to the binding metrics.

Gateway Version