Reads an OpenAPI description, deploys an API from it and validates the messages flowing through against that description. What runs is governed by the validateRequests, validateResponses and validateSecurity attributes; when enabled, Membrane validates:

Routing: the request path and HTTP method against the declared operations, including the OpenAPI 3.2 QUERY method and additionalOperations (an unknown path returns 404, an undeclared method 405).
Path, query and header parameters (type, required, enum and format), including the OpenAPI 3.2 in: querystring parameter.
Request and response bodies against their JSON Schema (JSON Schema 2020-12 for OpenAPI 3.1 and 3.2) for application/json, XML, application/x-www-form-urlencoded and multipart/form-data.
Streaming and sequential bodies item by item through the OpenAPI 3.2 itemSchema, for application/jsonl, application/json-seq, ND-JSON and text/event-stream.
XML bodies, including the OpenAPI 3.2 xml.nodeType (attribute, element, text, cdata) alongside the deprecated xml.attribute and xml.wrapped.
String content that carries another format, via contentMediaType, contentEncoding and contentSchema.
Response headers.
Declared security requirements (for example API keys and OAuth2 scopes) when validateSecurity is enabled.

Example Configuration

api:
   port: 2000
   openapi:
     - location: openapi/fruitshop-api.yaml
       validateRequests: yes
       validateResponses: yes

api:
   port: 2000
   openapi:
     - location: openapi/fruitshop-api.yaml
       validateRequests: yes
       validateResponses: yes

Syntax

openapi:
  dir: <string>
  location: <string>
  rewrite: {}
  validateRequests: <boolean>
  validateResponses: <boolean>
  validateSecurity: <boolean>
  validationDetails: <boolean>

openapi:
  dir: <string>
  location: <string>
  rewrite: {}
  validateRequests: <boolean>
  validateResponses: <boolean>
  validateSecurity: <boolean>
  validationDetails: <boolean>

Attributes

Name	Required	Default	Description	Examples
dir	false	-	Directory containing OpenAPI definitions to deploy.	openapi
location	false	-	Filename or URL pointing to an OpenAPI document. Relative filenames use the %MEMBRANE_HOME%/conf folder as base directory.	openapi/fruitstore-v1.yaml, https://api.predic8.de/shop/swagger
validateRequests	false	asInOpenAPI	Whether requests are validated against the OpenAPI description. When omitted, the setting is taken from the OpenAPI document's `x-membrane-validation` extension, which defaults to off. Enabling security validation also enables request validation.	yes
validateResponses	false	asInOpenAPI	Whether responses are validated against the OpenAPI description. When omitted, the setting is taken from the OpenAPI document's `x-membrane-validation` extension, which defaults to off.	yes
validateSecurity	false	asInOpenAPI	Whether requests are checked against the operation's security requirements (for example API keys and OAuth2 scopes). Enabling it also enables request validation. When omitted, the setting is taken from the OpenAPI document's `x-membrane-validation` extension, which defaults to off.	yes
validationDetails	false	asInOpenAPI	Whether validation error responses include the detailed list of validation errors. When omitted, the setting is taken from the OpenAPI document's `x-membrane-validation` extension, which defaults to on.	no

Child Structure

Element	Cardinality	Description
rewrite	0..1

Can be used in

api