About

This extension validates incoming HTTP requests against an OpenAPI specification file. It matches requests to operations and validate paths, methods, query parameters, headers, and request bodies against the defined schemas.

Key Features

  • Full request validation: Validates the HTTP method, path, path parameters, query parameters, request headers, and the request body against the OpenAPI spec.
  • OpenAPI 3.0 and 3.1 support: Load specifications in YAML or JSON format, either from a file or as inline content.
  • Configurable body size limit: Set a maximum request body size to buffer for validation. Requests exceeding the limit are rejected with a 413 status.
  • Dry-run mode: Log validation failures without enforcing them, useful for testing new specs in production.
  • Configurable deny responses: Customize the HTTP status code, body, and headers returned when a request fails validation.

Configuration Fields

Field Type Required Default Description
spec object yes - OpenAPI specification source; exactly one of inline or file must be set
spec.inline string yes* - Inline OpenAPI spec content (YAML or JSON)
spec.file string yes* - Path to the OpenAPI spec file (YAML or JSON)
max_body_bytes integer no 0 (no limit) Maximum body size to buffer; 0 disables the limit
allow_unmatched_paths boolean no false Allow requests to paths not in the spec
dry_run boolean no false Log failures without enforcing
deny_response object no - Response returned on validation failure
deny_response.status integer no 400 HTTP status code on validation failure
deny_response.body string no (error message) Response body on failure
deny_response.headers object no - Additional response headers on failure

* Exactly one of spec.inline or spec.file must be set.

Usage Examples

Minimal OpenAPI Spec

A minimal OpenAPI spec that validates requests to a /post endpoint. Only POST requests with a JSON body containing a required title field (string) are allowed.

# Create a minimal OpenAPI spec
cat > /tmp/openapi.yaml << 'EOF'
openapi: "3.0.0"
info:
  title: Example API
  version: "1.0"
paths:
  /post:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [title]
              properties:
                title:
                  type: string
      responses:
        "200":
          description: Successful response
EOF

# Run the extension
boe run --extension openapi-validator --config '{
  "spec": {"file": "/tmp/openapi.yaml"}
}'

# Valid request
curl -X POST -H "Content-Type: application/json" \
  -d '{"title": "hello"}' http://localhost:10000/post
# => 200 OK (proxied to upstream)

# Missing required field
curl -X POST -H "Content-Type: application/json" \
  -d '{"other": "field"}' http://localhost:10000/post
# => 400 Bad Request

# Unknown path
curl http://localhost:10000/unknown
# => 400 Bad Request

Body Validation with Size Limit

Validate request bodies against the schema defined in the OpenAPI spec. Set a maximum body size to protect against oversized payloads.

boe run --extension openapi-validator --config '{
  "spec": {"file": "/path/to/openapi.yaml"},
  "max_body_bytes": 1048576
}'

# Valid POST with conforming body
curl -X POST -H "Content-Type: application/json" \
  -d '{"name": "alice"}' http://localhost:10000/api/users
# => 201 Created

# POST with body exceeding size limit
curl -X POST -H "Content-Type: application/json" \
  -d @large-file.json http://localhost:10000/api/users
# => 413 Request body too large

Dry-Run Mode

Enable dry-run mode to log validation failures without blocking traffic. Useful for testing a new API spec before enforcing it.

boe run --extension openapi-validator --config '{
  "spec": {"file": "/path/to/openapi.yaml"},
  "dry_run": true
}'

Custom Deny Response

Customize the response returned when a request fails validation.

boe run --extension openapi-validator --config '{
  "spec": {"file": "/path/to/openapi.yaml"},
  "deny_response": {
    "status": 422,
    "body": "Request does not conform to API specification",
    "headers": {"content-type": "text/plain"}
  }
}'