Skip to content

Commit

Permalink
Fix x-ms-examples how to doc pointing to providerhub docs (#358)
Browse files Browse the repository at this point in the history
  • Loading branch information
timotheeguerin authored Mar 4, 2024
1 parent 7dd798b commit 4b26297
Showing 1 changed file with 7 additions and 13 deletions.
20 changes: 7 additions & 13 deletions docs/howtos/migrate-swagger/x-ms-examples.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,22 +39,16 @@ 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.
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
```
```bash
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:
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.
- 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.
Expand Down

0 comments on commit 4b26297

Please sign in to comment.