Learn the vocabulary for writing OpenAPI examples: example values, x-examples extension, realistic data, and example-driven documentation.
0 / 5 completed
1 / 5
In an OpenAPI spec, what is the difference between `example` (on a schema field) and `examples` (on a request/response)?
In OpenAPI 3.x, `example` on a schema or field provides a single inline value. `examples` at the parameter or media-type level is a map of named example objects, each with a summary, description, and value — useful for showing multiple scenarios.
2 / 5
What is the 'realistic example data' principle in API documentation?
Realistic examples use values that look like real data — 'john.smith@example.com' instead of 'user@user.com', 'ORD-20241105-7823' instead of 'string' — making documentation much easier to understand and use.
3 / 5
A reviewer comments 'avoid placeholder examples'. What does this mean?
Placeholder examples like `"name": "string"` or `"count": 0` are generated defaults that convey no meaning. Good documentation replaces them with realistic values that illustrate actual usage.
4 / 5
What is the `x-examples` extension in OpenAPI specs typically used for?
In OpenAPI 2.0 (Swagger), the `examples` map at the operation level isn't supported the same way. The `x-examples` vendor extension is used by many tools to add named examples in Swagger 2.0 specs.
5 / 5
What is 'example-driven documentation' in the context of API specs?
Example-driven documentation prioritises clear, realistic examples as the primary communication tool. Developers can understand what an API does from the examples first, with schema details as reference, rather than having to infer behaviour from abstract type definitions.