Add how to docs for dealing with x-ms-examples

docs/howtos/migrate-swagger/x-ms-examples.md

@@ -0,0 +1,61 @@
+---
+title: x-ms-examples
+---
+
+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.
+
+:::warn
+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](https://github.com/Azure/oav). You can run that on the generated openapi.json file.
+
+1. 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.
+
+   ```bash
+   oav generate-examples openapi.json
+   ```
+
+2. (**Recommended**) Generating high quality examples from API Scenario test. Refer to [API Test section](getstarted/providerhub/step03-api-testing.md). It will validate the API quality and generate Swagger examples from live traffic in API Scenario test.
+
+   ```bash
+   oav run <scenario-file> --spec <spec-file> --generateExample
+   ```
+
+   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.
+
+:::warn
+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.
+:::