There are a few things that could be done to improve the examples in our OpenAPI Schema:
- Use less ambiguous example values. E.g. For the GET item response, `"id": "Q11"` rather than `"id": "string"`. `"string"` is ambiguous as it could mean 'replace "string" with any type string' or it could mean 'the actual string "string"' like is possible for `property.data-type`.
- Add an example to the lowest level fields where it makes sense. E.g. `site`, `title`, and `badges` of `sitelinks`. Labels, descriptions, and aliases are probably okay how they are.
- Ensure all requests and responses have good examples. Auto-generated ones are fine as long as they are clear.
- Add/improve statement examples with property data-types other than `string`
- Remove long examples from top level schemas (e.g. `Statements` in `global/schema-parts.json`). These top level examples are better in the request and response objects where there is proper formatting and syntax highlighting in the Swagger UI. Labels, descriptions, and aliases are probably okay how they are.