x-ms-examples example files

The x-ms-examples is automatically populated in the generated OpenAPI 2.0 when using the typespec-autorest emitter. If you use the skip-example-copying in typespec-autorest configuration as suggested below, examples will automatically be picked up from the examples directory adjacent to the spec. If you do not use this option, the examples must be placed in the examples-dir directory (default {project-root}/examples). Examples must all have the operationId property, allowing each example to be matched with the appropriate operation.

Recommended configuration

We recommend using skip-example-copying together with an examples-dir that places examples under the versioned output folder. This keeps example files co-located with the generated swagger and avoids copying files during compilation.

options:
  "@azure-tools/typespec-autorest":
    emitter-output-dir: "{project-root}"
    output-file: "{emitter-output-dir}/{version-status}/{version}/openapi.json"
    examples-dir: "{emitter-output-dir}/{version-status}/{version}/examples"
    skip-example-copying: true

With this configuration, example files live alongside the generated swagger at {version-status}/{version}/examples/ and are referenced via relative paths (e.g., examples/getPet.json).

Example structure

Single version structure (versioned API with examples co-located in output)

main.tsp
tspconfig.yaml
Directorystable/
- Directory2021-01-01/
  - openapi.json
  - Directoryexamples/
    example1.json
    example2.json

Multi version structure

main.tsp
tspconfig.yaml
Directorystable/
- Directory2021-01-01/
  - openapi.json
  - Directoryexamples/
    example1.json
    example2.json
- Directory2021-01-02/
  - openapi.json
  - Directoryexamples/
    example1.json
    example2.json

Generate the examples

To generate the examples you can use oav. You can run that on the generated openapi.json file.

Generating basic examples and then manually modify the values. It will generate two examples for each operation: one contains minimal properties set, the other contains the maximal properties set. Since the auto-generated examples consist of random values for most types, you need replace them with meaningful values.

oav generate-examples openapi.json

Note, latest OAV tool should automatically generate the following. However, if you are generating the examples manually, please ensure you have:

include title field and make sure it is descriptive and unique for each operation.
include operationId. This is used to match with declared operations in TypeSpec and correctly output in swagger.