x-ms-examples example files
The x-ms-examples
is automatically populated in the generated OpenAPI 2.0 when using the typespec-autorest
emitter.
The examples must be placed in the examples-directory
(default to {project-root}/examples
) and have the operationdId
property.
Do not use @extension("x-ms-examples", "<value>")
.
Example structure​
Example below assume example-directory
is {project-root}/examples
.
- Single version structure
main.tsp
examples/
example1.json
example2.json
- Multi version structure
main.tsp
examples/
2021-01-01/
example1.json
example2.json
2021-01-02/
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.
The examples are now in the examples directory relative to the output openapi.json. You must now copy them to the examples directory in the project root. The typespec-autorest emitter will then copy them back to the correct location when generating the OpenAPI 2.0.