Vault-generated OpenAPI 3.0.2 spec exposes multi-segment {path} parameters not compatible with standard OAS tooling

[sofiafernandezmoreno]

Vault 1.18.0 generates an OpenAPI 3.0.2 specification that defines endpoints such as:

/kv/data/{path}

However, Vault accepts multi-segment values for {path}, e.g.:

/kv/data/apip/gateway/dev/common

This behavior contradicts the OpenAPI 3.x specification, where path parameters match a single segment only.

As a result, downstream OAS validators (including API gateways such as Kong) reject valid Vault requests because the generated OAS does not reflect this multi-segment behavior.

To Reproduce
Steps to reproduce the behavior:

1. Retrieve OAS:

GET /sys/internal/specs/openapi?generic_mount_paths=false

or API Explorer

2. Use the generated spec to validate the following request:

GET /kv/data/apip/gateway/dev/common

matches only one segment (e.g. /kv/data/foo) per OpenAPI rules.

Vault accepts unlimited nested segments, but the OAS spec does not express this.
Expected behavior
The OpenAPI document should reflect the real behavior of Vault’s KV engine, such as:

• {path} allowing slashes
• an extension indicating prefix/multi-segment behavior
• a regex pattern
• or vendor extension like:

x-vault-multi-segment: true

so that third-party OAS tools can interpret Vault semantics correctly.

Environment:

• Vault version: 1.18.0
  Vault server configuration file(s):

vault-oas.json

Actual Behavior

• Vault processes multi-segment paths correctly.
• The OAS consumer rejects them as invalid, because the spec says {path} is a single segment string with no extensions and no regex allowing /.

Kong engineering explicitly confirmed that this is beyond what OAS 3.x supports and stated:

Vault is deviating from the OpenAPI specification by allowing multi-segment path parameters.
The OAS generated by Vault does not describe this behavior.

Impact

This breaks integration with API Gateways that enforce OAS (Kong)

These systems rely on strict OpenAPI interpretation and therefore reject valid Vault API calls.

[heatherezell]

Hi there! I've sent this to the engineering teams, but if you happen to be an Enterprise customer please also open a case with support, as that will help get eyes on this even faster. Thanks! :)

[sofiafernandezmoreno]

Hi,
We are not in Enterprise but thank you for taking a look