OpenAPI 3.0 and 3.1 support in Rust

Accepted OpenAPI versions

“Supported” does not mean every valid extension or uncommon keyword changes code generation. Unknown fields are retained where possible for compatibility, but an unrecognized or analysis-only field may not affect generated Rust.

JSON Schema 2020-12 shapes

OpenAPI 3.1 aligns its Schema Object with JSON Schema 2020-12. One visible change is nullable typing: a field can use type: [string, "null"] instead of OpenAPI 3.0’s nullable: true.

components:
  schemas:
    Event:
      type: object
      properties:
        received_at:
          type: [string, "null"]
          format: date-time
        payload:
          oneOf:
            - $ref: '#/components/schemas/TextPayload'
            - $ref: '#/components/schemas/ImagePayload'

The type array is used to determine Rust optionality. The parser also has typed representations for keywords includingprefixItems, contains, patternProperties, dependentSchemas,if/then/else, $defs, and dynamic reference fields.

oneOf, anyOf, allOf, and discriminators

Composition is one of the reasons this generator is tested against large, real-world documents. A union of object schemas with a discriminator can become a Serde tagged enum. A union that mixes a string enum and object variants becomes an untagged enum so both wire shapes deserialize.

• oneOf and anyOf can produce Rust enums based on the branch shapes.
• allOf properties are combined when the shape can be represented safely.
• Explicit discriminator mappings and implicit discriminators inferred from const properties are handled for tested patterns.
• Inline request, response, and parameter objects receive generated Rust names.
• Open-ended string enums can include a Custom(String) fallback.

Union behavior depends on the exact schema shape. Add a focused fixture before relying on an uncommon combination; the repository’s snapshot suite is the clearest source of expected generated output.

Map OpenAPI formats to Rust scalars

Every format mapping can be opted out in TOML when a project prefers raw strings or a different domain type.

Separate modeled fields from runtime support

The internal OpenAPI model includes components such as servers, security schemes, OAuth flows, encodings, headers, callbacks, links, tags, external documentation, and discriminators. Modeling lets the parser retain and analyze those fields; it does not promise a runtime implementation for every behavior.

For example, generated clients can apply Bearer, API-key, and custom header authentication, but modeled mutual TLS credentials are not configured by the generated client. Schema constraints such as minimum, maxLength, andpattern are emitted as documentation and are not runtime validators.

Experimental OpenAPI 3.2 support

OpenAPI 3.2 documents parse with an experimental warning. Selected deltas are typed, and a smaller set changes generation. The QUERY method and additional Path Item operations, for example, can emit client methods throughreqwest::Method::from_bytes(...). Other new fields may only be captured for forward compatibility.

Do not describe this as full OpenAPI 3.2 support. Review generated code and add a fixture for every 3.2 feature your application depends on.

Verify the contract you depend on

1. Run openapi-to-rust generate openapi.yaml --dry-run to inspect planned output.
2. Generate and run cargo check in your application.
3. Add serialization round-trip tests for high-risk union and parameter shapes.
4. Use --check in CI to detect drift.
5. Contribute a minimized fixture when an uncommon keyword affects your API.

For broader evidence, see the real-world compatibility corpus and CI policy.