Skip to content

tsp-openapi3: import examples #3866

Open

Description

Clear and concise description of the problem

Now that #2700 is complete, the tsp-openapi tool should be updatet to do the reverse and add example(s) to the TypeSpec. (A single opExample/example if using example, multiple if using examples.)

Checklist

  • Follow our Code of Conduct
  • Read the docs.
  • Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

Activity

  1. Arithmomaniac commented on Aug 1, 2024

    @Arithmomaniac
    Author

    Mark Cowlishaw (@markcowl) Timothee Guerin (@timotheeguerin) thanks for backlogging, hopefully it can at least be in beta by Hack

  2. baywet commented on Nov 20, 2026

    @baywet
    Member

    I verified a concrete Schema Object round-trip case with @typespec/openapi3 1.18.0, using OpenAPI 3.2.0 for both input and output. This is about the JSON Schema examples array, not the named examples map on an OpenAPI Media Type Object.

    Repro

    Save this as openapi.yaml and run tsp-openapi3 openapi.yaml --output-dir converted:

    openapi: 3.2.0
    info:
      title: Pets
      version: '1'
    paths: {}
    components:
      schemas:
        Pet:
          type: object
          required: [name]
          properties:
            name:
              type: string
          examples:
            - name: Fluffy
            - name: Spot
            - name: Mochi

    Actual: The converter emits the model with the required name property, but silently drops the entire examples array. The generated declaration has no @example decorators:

    model Pet {
      name: string;
    }

    Expected: Import each array entry as its own @example decorator on Pet. Re-emitting to OpenAPI 3.2.0 should produce a single components.schemas.Pet.examples array containing all three instance values, without a singular example field. The desired round trip preserves the original array order as well as the values.

    Emitter behavior to account for

    No emitter feature is needed to represent multiple schema examples: I also verified that repeated @example decorators on a model already emit a single schema-level examples array in 3.2.0. In 1.18.0 the emitted order is the reverse of the written decorator order. For this input, writing the decorators in the following order would account for that behavior:

    @example(#{ name: "Mochi" })
    @example(#{ name: "Spot" })
    @example(#{ name: "Fluffy" })
    model Pet {
      name: string;
    }

    A regression test could import this fixture, compile the generated TypeSpec, re-emit OpenAPI 3.2.0, and compare components.schemas.Pet.examples to the input array. A one-entry array is also worth covering: it should still round-trip as examples: [...], not as the deprecated OpenAPI Schema Object example field. Media Type Object example maps and their Example Object metadata are a separate case.

    References: OpenAPI 3.2.0 Schema Object and JSON Schema Draft 2020-12 examples.

  3. baywet commented on Nov 20, 2026

    @baywet
    Member

    I opened #12627 to track importing OpenAPI response media-type example and examples as @opExample.returnType. It includes a minimal repro and round-trip cases for multiple response statuses, media types, and named examples.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

featureNew feature or requestopenapi3:converterIssues for @typespec/openapi3 openapi to typespec convertertriaged:core

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions