Specification extensions
OpenAPI, Swagger 2.0 and AsyncAPI documents keep what the specification has no field for in x-
fields, the specification extensions. This page lists the extensions API Genie reads: its own, under
x-apigenie, and those of other tools that its generators, linters, differ and mock server
understand. Each entry says where the extension goes, the value it takes and which tools read it;
the page of each tool holds the details.
An extension that is not listed here is kept as it is, and read by no tool:
apigenie formatkeeps it. An order of properties never lists extensions, so they follow the listed fields, and theextensionorder applies inside their values (Property order).apigenie diffreports an extension added, removed or changed, and rates the change with theextensionsmap of the node type’s rules,*for the names not listed, or withdefaults.extensions.apigenie convertcopies extensions from a Swagger 2.0 document to the OpenAPI document it writes.- The documentation components show none of these. The Redoc extensions (
x-tagGroups,x-displayName,x-logo,x-codeSamples) are not read.
The extensions a generator reads can live in an overlay of that generator instead of in the
document, passed with --overlay (Overlays).
API Genie’s own
| Extension | Where it goes, its value, and the tools that read it |
|---|---|
x-apigenie.codegen.name |
Where: A component schema; in AsyncAPI also a channel, a message or an operation. Value: The name of the generated type, class, module or schema; on a channel or a message, the base of its names; on an operation, the name of its function. Read by: The generators: client elixir, fetch, go, go (AsyncAPI), java (AsyncAPI), kafkajs, python, python (AsyncAPI), rust, swift, ws; server axum, express, faststream, go, go (AsyncAPI), hummingbird, kafkajs, orpc, phoenix, spring (AsyncAPI), vapor, ws; schema zod |
x-apigenie.codegen.controller-name |
Where: An operation or its path item. Value: The class, module, resource or interface the operation goes into, instead of its tag or path. Read by: client csharp, java, python (since 0.12.0); server aspnet, express, fastapi, spring |
x-apigenie.codegen.action-name |
Where: An operation. Value: The name of the method, function, handler or procedure, or of a webhook sender, instead of the operationId.Read by: client csharp, elixir, fetch, go, java, python, rust, swift; server aspnet, axum, express, fastapi, go, hummingbird, orpc, phoenix, spring, vapor |
x-apigenie.codegen.disabled |
Where: An operation or its path item; in AsyncAPI a channel or an operation. Value: true leaves it out of the generated code.Read by: The generators of clients and servers from OpenAPI and AsyncAPI documents, except client elixir (AsyncAPI), and server orpc and phoenix (AsyncAPI) |
x-apigenie-lint-disable, alias x-lint-disable |
Where: Any object, the root included. Value: A list of rule ids, disabled for the object and everything nested in it. Read by: apigenie lint of OpenAPI, Swagger 2.0 and AsyncAPI documents |
x-apigenie-mock |
Where: An OpenAPI operation or its path item. Value: status, example, dynamic, body, body_file, headers, latency, jitter, drop, bandwidth, delay, probability, validate_request, scenarios, resource.Read by: apigenie-server; resource makes a CRUD resource |
x-apigenie-mock |
Where: An OpenAPI response. Value: delay, latency, jitter, headers.Read by: apigenie-server |
x-apigenie-mock |
Where: An AsyncAPI send operation.Value: interval (milliseconds), count, jitter, messages, publish: false.Read by: apigenie-server |
x-apigenie-mock-faker, alias x-faker |
Where: A schema. Value: A faker provider: a name, {name: [arguments]}, or {provider, args, options}; x-apigenie-mock-faker wins over x-faker.Read by: apigenie-server, data |
x-apigenie-broadway |
Where: The Kafka binding of an AsyncAPI operation or channel. Value: batch_size and batch_timeout of the Broadway pipeline.Read by: server phoenix (AsyncAPI) |
x-apigenie-lint-disable, x-apigenie-mock, x-apigenie-mock-faker and the codegen members of
x-apigenie are part of the compatibility promise.
X-Apigenie-Mock-* and X-Apigenie-Test are HTTP headers and gRPC metadata, not extensions: see
Responses, Protobuf and gRPC
and Recording.
Lifecycle and governance
| Extension | Where it goes, its value, and the tools that read it |
|---|---|
x-sunset |
Where: Next to deprecated: true: an operation, a parameter, a schema, a property (beside its $ref or where it is defined).Value: An RFC 3339 date ( 2027-01-31) or date-time after which the element may go.Read by: apigenie diff, the sunset_passed condition of OpenAPI and Swagger 2.0 rules; written by apigenie evolve plan |
x-deprecated-enum |
Where: A schema with an enum.Value: The enum values that are deprecated; the schema’s x-sunset says when they may go.Read by: apigenie diff, the deprecated condition; written by apigenie evolve plan |
x-audience |
Where: info.Value: internal-team, internal-company, partner or public.Read by: The audience-defined rule of OpenAPI, Swagger 2.0 and AsyncAPI |
x-id |
Where: info.Value: A UUID, or a value matching the rule’s pattern; the rule’s attribute can name another extension.Read by: The id-defined rule of OpenAPI and Swagger 2.0 |
OpenAPI 3.2 fields in 3.0 and 3.1 documents
The OpenAPI reader reads these extensions as the field of a later version they stand for:
x-webhooks in a 3.0 document, the others in a 3.0 or 3.1 document. The tools that write such a
document write the field back as the extension.
| Extension | Where it goes, its value, and the tools that read it |
|---|---|
x-itemSchema |
Where: A media type. Value: itemSchema: the schema of each item of a streamed body.Read by: client csharp, fetch, go, java, rust, swift; server aspnet, axum, express, hummingbird, orpc, vapor |
x-defaultMapping |
Where: A discriminator. Value: defaultMapping: the schema of the values the mapping does not list.Read by: client csharp, elixir, fetch, go, java, python, rust, swift; server aspnet, axum, express, fastapi, go, hummingbird, orpc, phoenix, spring, vapor |
x-webhooks |
Where: The root of an OpenAPI 3.0 document. Value: An object: webhooks (OpenAPI 3.1), the requests the API sends to its subscribers. Another value stays an extension.Read by: The OpenAPI reader, so the linter, diff, changelog and the generators see them; server aspnet, express and orpc generate their senders |
x-nodeType |
Where: An XML object. Value: nodeType: element, attribute, text, cdata or none.Read by: apigenie-server for XML bodies; written by apigenie convert from WSDL |
Code generation
Most of these are the names of OpenAPI Generator and, for Go, of oapi-codegen, read by the API Genie generators of the same languages.
| Extension | Where it goes, its value, and the tools that read it |
|---|---|
x-internal |
Where: An operation or its path item. Value: true leaves the operation out; client fetch, go and elixir, server phoenix and mcp and, since 0.12.0, client python, server go, client swift and the Swift servers (vapor, hummingbird) keep it with internal_operations; since 0.12.0, server fastapi serves it but leaves it out of the served OpenAPI document. Client rust and server axum generate it behind the cargo feature internal (internal_operations: include or exclude instead).Read by: client csharp, elixir, fetch, go, java, python, rust, swift; server aspnet, axum, fastapi (since 0.12.0), go (since 0.12.0), hummingbird, mcp, phoenix, spring, vapor. The other targets generate the operation. |
x-mcp |
Where: An operation or its path item. Value: false: the operation is not a tool.Read by: server mcp |
x-codegen-request-body-name |
Where: An operation or its request body. Value: The name of the body parameter. Read by: client java, server fastapi, spring; written by the editor’s Swagger 2.0 import |
x-enum-varnames |
Where: A schema with an enum.Value: The names of the constants, in the order of the values. Read by: client csharp, csharp (AsyncAPI), go, go (AsyncAPI), java, python, python (AsyncAPI), rust, swift; server aspnet, axum, aspnet (AsyncAPI), faststream, go, go (AsyncAPI), hummingbird, spring, vapor |
x-enumNames |
Where: A schema with an enum.Value: The same as x-enum-varnames.Read by: client go, go (AsyncAPI), python, python (AsyncAPI), rust, swift; server axum, faststream, go, go (AsyncAPI), hummingbird, vapor |
x-enum-names |
Where: A schema with an enum.Value: The same as x-enum-varnames.Read by: client csharp, csharp (AsyncAPI); server aspnet, aspnet (AsyncAPI) |
x-enum-descriptions |
Where: A schema with an enum.Value: The documentation comments of the constants, in the order of the values. Read by: client csharp, csharp (AsyncAPI), go, go (AsyncAPI), java, rust, swift; server aspnet, axum, aspnet (AsyncAPI), go, go (AsyncAPI), hummingbird, spring, vapor |
x-enumDescriptions |
Where: A schema with an enum.Value: The same as x-enum-descriptions.Read by: client csharp, csharp (AsyncAPI); server aspnet, aspnet (AsyncAPI) |
Go
Read by client go and go (AsyncAPI), and server go and go (AsyncAPI).
| Extension | Where | Value |
|---|---|---|
x-go-name |
A schema or a property | The name of the type or of the field |
x-go-type |
A schema | The Go type to use, e.g. decimal.Decimal |
x-go-type-import |
A schema with x-go-type |
{path: ...}: the package of the type |
x-go-type-skip-optional-pointer |
A property | true: the optional field is not a pointer |
x-go-json-ignore |
A property | true: the field gets the tag json:"-" |
x-omitempty |
A property | true or false overrides the omitempty of the field |
Rust
Read by client rust and server axum, since 0.12.0.
| Extension | Where | Value |
|---|---|---|
x-rust-name |
A schema | The name of its type |
x-rust-type |
A schema | The Rust type to use, a path such as my_crate::Money, or a name type_mappings maps to one |
Swift
Read by client swift and server hummingbird and vapor.
| Extension | Where | Value |
|---|---|---|
x-swift-name |
A schema or a property | The name of the type or of the property |
Java and Spring
Read by client java and server spring; a value that is a list of annotations or arguments can also be one string.
| Extension | Where | Value |
|---|---|---|
x-class-extra-annotation |
A schema | Annotations of its class, e.g. ['@Entity'] |
x-implements |
A schema | Interfaces its class implements |
x-field-extra-annotation |
A property or a parameter | Annotations of the field or of the method parameter |
x-extra-annotation |
A property | Annotations of the getter |
x-setter-extra-annotation |
A property | Annotations of the setter |
x-pattern-message, x-size-message, x-minimum-message, x-maximum-message |
A property | The message of @Pattern, @Size, @Min or @DecimalMin, @Max or @DecimalMax |
x-jackson-json-include-policy |
A property | The @JsonInclude policy, e.g. non_empty; none for no annotation |
x-jackson-json-setter-nulls |
A property | @JsonSetter(nulls = ...), e.g. skip; none for no annotation |
x-parent |
A schema | true: the superclass of the schemas extending it with allOf, without a discriminator |
x-discriminator-value |
A schema extending one with a discriminator | Its value in @JsonSubTypes; the name of the schema by default |
x-jackson-default-impl |
A schema with a discriminator | The defaultImpl of its @JsonTypeInfo |
x-operation-extra-annotation |
An operation | Annotations of its method; not with spring-http-interface |
x-version-param |
A header or query parameter | true adds it to the headers or params of @RequestMapping; not with spring-http-interface |
x-spring-paginated |
An operation | true replaces page, size and sort with a Pageable; false keeps them with autoXSpringPaginated. Spring only |
x-spring-provide-args |
An operation | Further arguments of its method, e.g. ['@RequestAttribute("tenant") String tenant']. Spring only, not with spring-http-interface |
Swagger 2.0
| Extension | Where it goes, its value, and the tools that read it |
|---|---|
x-nullable |
Where: A schema. Value: true: null is a valid value.Read by: apigenie convert (adds null to the type), schema zod, the documentation components, the editor’s Swagger 2.0 import |
x-example |
Where: A parameter or a schema. Value: An example value. Read by: apigenie convert (becomes example), the editor’s Swagger 2.0 import; the documentation components, on a parameter |
Written by apigenie convert
A document converted from WSDL keeps what OpenAPI has no field for in extensions. No tool reads them back.
| Extension | Where | Value |
|---|---|---|
x-wsdl-target-namespace |
info |
The targetNamespace of the WSDL |
x-soap-address |
An operation | The address of the port |
x-soap-action |
An operation | The SOAPAction of the operation |