OpenAPI Examples Vocabulary Quiz
Learn the vocabulary for writing OpenAPI examples: example values, x-examples extension, realistic data, and example-driven documentation.
0 / 26 completed
1 / 26
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 / 26
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 / 26
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 / 26
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 / 26
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.
6 / 26
Sarah: 'Hey team, I'm struggling to understand the API response for the user profile endpoint. The documentation shows an example field on the 'address' schema, but it's just a single address object. However, I can't find any full example responses anywhere! What am I missing?'This question assesses understanding of a common misconception. The
example field *within* a schema defines a single instance of that data type—think of it as a sample record for that field. Conversely, 'examples' (often found in request/response sections) are designed to show you how the entire API interaction looks, including multiple fields and their relationships. It's crucial to differentiate between representing a single value and demonstrating a full usage scenario.7 / 26
PR Description:
"Fix: Updated user profile endpoint to return a full example response. Added an `x-examples` extension to the OpenAPI spec for clarity and consistency. The previous documentation only provided individual schema examples, leading to confusion about the overall response structure."x-examples extensions are a crucial tool for providing complete, runnable example responses within an OpenAPI specification. This PR demonstrates the correct usage – by explicitly adding a full response alongside schema definitions, it alleviates confusion and provides developers with a tangible representation of the expected API behavior. The realistic example data principle dictates that documentation should mirror actual production output, which is precisely what this extension achieves.8 / 26
John: "I'm reviewing this PR for the new payment service. The documentation says we should include example responses in our OpenAPI spec, but I'm seeing just individual schema examples listed. Is that really necessary, or can we just focus on documenting each field individually?"While documenting individual schema fields is important, providing a complete example response is crucial for developers to understand the *entire* structure of the API and how data is returned. The goal of example responses is to demonstrate the expected format and relationships between different elements within the response, allowing developers to quickly integrate the service without needing to manually deduce the full response structure. Focusing solely on individual fields can lead to confusion about how those fields fit together in a meaningful context.
9 / 26
Reviewer: 'The examples in the OpenAPI spec are too granular. We need to show developers *how* a complete response looks, not just individual fields.'
Which of the following best describes what Reviewer is referring to when discussing example responses in an OpenAPI specification?
The reviewer is advocating for 'example-driven documentation,' a critical principle in OpenAPI specification design. They're emphasizing the importance of showing developers *how* an entire response looks – including all fields and their relationships – rather than just providing isolated schema definitions. This approach reduces ambiguity and makes it easier for developers to understand how to consume the API, especially when dealing with complex nested structures or data transformations. Providing a complete example allows developers to immediately see the expected format and values without having to manually construct the response based only on individual field types.
10 / 26
Sarah: 'Hey team, I'm struggling to understand the API response for the user profile endpoint. The documentation shows an example field on the 'address' schema, but it's just a single address object. However, I can't find any full example responses anywhere! What am I missing?'This question assesses understanding of a common misconception. The
example field *within* a schema defines a single instance of that data type—think of it as a sample record for that field. Conversely, 'examples' (often found in request/response sections) are designed to show you how the entire API interaction looks, including multiple fields and their relationships. It's crucial to differentiate between representing a single value and demonstrating a full usage scenario.11 / 26
PR Description:
"Fix: Updated user profile endpoint to return a full example response. Added an `x-examples` extension to the OpenAPI spec for clarity and consistency. The previous documentation only provided individual schema examples, leading to confusion about the overall response structure."x-examples extensions are a crucial tool for providing complete, runnable example responses within an OpenAPI specification. This PR demonstrates the correct usage – by explicitly adding a full response alongside schema definitions, it alleviates confusion and provides developers with a tangible representation of the expected API behavior. The realistic example data principle dictates that documentation should mirror actual production output, which is precisely what this extension achieves.12 / 26
John: "I'm reviewing this PR for the new payment service. The documentation says we should include example responses in our OpenAPI spec, but I'm seeing just individual schema examples listed. Is that really necessary, or can we just focus on documenting each field individually?"While documenting individual schema fields is important, providing a complete example response is crucial for developers to understand the *entire* structure of the API and how data is returned. The goal of example responses is to demonstrate the expected format and relationships between different elements within the response, allowing developers to quickly integrate the service without needing to manually deduce the full response structure. Focusing solely on individual fields can lead to confusion about how those fields fit together in a meaningful context.
13 / 26
Reviewer: 'The examples in the OpenAPI spec are too granular. We need to show developers *how* a complete response looks, not just individual fields.'
Which of the following best describes what Reviewer is referring to when discussing example responses in an OpenAPI specification?
The reviewer is advocating for 'example-driven documentation,' a critical principle in OpenAPI specification design. They're emphasizing the importance of showing developers *how* an entire response looks – including all fields and their relationships – rather than just providing isolated schema definitions. This approach reduces ambiguity and makes it easier for developers to understand how to consume the API, especially when dealing with complex nested structures or data transformations. Providing a complete example allows developers to immediately see the expected format and values without having to manually construct the response based only on individual field types.
14 / 26
Sarah: 'Hey team, I'm struggling to understand the API response for the user profile endpoint. The documentation shows an example field on the 'address' schema, but it's just a single address object. However, I can't find any full example responses anywhere! What am I missing?'This question assesses understanding of a common misconception. The
example field *within* a schema defines a single instance of that data type—think of it as a sample record for that field. Conversely, 'examples' (often found in request/response sections) are designed to show you how the entire API interaction looks, including multiple fields and their relationships. It's crucial to differentiate between representing a single value and demonstrating a full usage scenario.15 / 26
PR Description:
"Fix: Updated user profile endpoint to return a full example response. Added an `x-examples` extension to the OpenAPI spec for clarity and consistency. The previous documentation only provided individual schema examples, leading to confusion about the overall response structure."x-examples extensions are a crucial tool for providing complete, runnable example responses within an OpenAPI specification. This PR demonstrates the correct usage – by explicitly adding a full response alongside schema definitions, it alleviates confusion and provides developers with a tangible representation of the expected API behavior. The realistic example data principle dictates that documentation should mirror actual production output, which is precisely what this extension achieves.16 / 26
John: "I'm reviewing this PR for the new payment service. The documentation says we should include example responses in our OpenAPI spec, but I'm seeing just individual schema examples listed. Is that really necessary, or can we just focus on documenting each field individually?"While documenting individual schema fields is important, providing a complete example response is crucial for developers to understand the *entire* structure of the API and how data is returned. The goal of example responses is to demonstrate the expected format and relationships between different elements within the response, allowing developers to quickly integrate the service without needing to manually deduce the full response structure. Focusing solely on individual fields can lead to confusion about how those fields fit together in a meaningful context.
17 / 26
Reviewer: 'The examples in the OpenAPI spec are too granular. We need to show developers *how* a complete response looks, not just individual fields.'
Which of the following best describes what Reviewer is referring to when discussing example responses in an OpenAPI specification?
The reviewer is advocating for 'example-driven documentation,' a critical principle in OpenAPI specification design. They're emphasizing the importance of showing developers *how* an entire response looks – including all fields and their relationships – rather than just providing isolated schema definitions. This approach reduces ambiguity and makes it easier for developers to understand how to consume the API, especially when dealing with complex nested structures or data transformations. Providing a complete example allows developers to immediately see the expected format and values without having to manually construct the response based only on individual field types.
18 / 26
Sarah: 'Hey team, I'm struggling to understand the API response for the user profile endpoint. The documentation shows an example field on the 'address' schema, but it's just a single address object. However, I can't find any full example responses anywhere! What am I missing?'This question assesses understanding of a common misconception. The
example field *within* a schema defines a single instance of that data type—think of it as a sample record for that field. Conversely, 'examples' (often found in request/response sections) are designed to show you how the entire API interaction looks, including multiple fields and their relationships. It's crucial to differentiate between representing a single value and demonstrating a full usage scenario.19 / 26
PR Description:
"Fix: Updated user profile endpoint to return a full example response. Added an `x-examples` extension to the OpenAPI spec for clarity and consistency. The previous documentation only provided individual schema examples, leading to confusion about the overall response structure."x-examples extensions are a crucial tool for providing complete, runnable example responses within an OpenAPI specification. This PR demonstrates the correct usage – by explicitly adding a full response alongside schema definitions, it alleviates confusion and provides developers with a tangible representation of the expected API behavior. The realistic example data principle dictates that documentation should mirror actual production output, which is precisely what this extension achieves.20 / 26
John: "I'm reviewing this PR for the new payment service. The documentation says we should include example responses in our OpenAPI spec, but I'm seeing just individual schema examples listed. Is that really necessary, or can we just focus on documenting each field individually?"While documenting individual schema fields is important, providing a complete example response is crucial for developers to understand the *entire* structure of the API and how data is returned. The goal of example responses is to demonstrate the expected format and relationships between different elements within the response, allowing developers to quickly integrate the service without needing to manually deduce the full response structure. Focusing solely on individual fields can lead to confusion about how those fields fit together in a meaningful context.
21 / 26
Reviewer: 'The examples in the OpenAPI spec are too granular. We need to show developers *how* a complete response looks, not just individual fields.'
Which of the following best describes what Reviewer is referring to when discussing example responses in an OpenAPI specification?
The reviewer is advocating for 'example-driven documentation,' a critical principle in OpenAPI specification design. They're emphasizing the importance of showing developers *how* an entire response looks – including all fields and their relationships – rather than just providing isolated schema definitions. This approach reduces ambiguity and makes it easier for developers to understand how to consume the API, especially when dealing with complex nested structures or data transformations. Providing a complete example allows developers to immediately see the expected format and values without having to manually construct the response based only on individual field types.
22 / 26
During a code review of the new `orders` API endpoint, Mark comments: 'I'm finding it difficult to visualize how the entire response looks when I call this endpoint. The OpenAPI spec shows me individual schema definitions for order items, but not a complete example with all fields populated.' Which of the following best captures Mark's concern?
Mark is expressing frustration with the granularity of the OpenAPI examples. He wants to see a *complete* response example, not just individual schema definitions. This highlights the importance of providing developers with context and illustrating how all fields interact within a full response – a key benefit of including `x-examples`.
23 / 26
In a Slack channel discussing API documentation improvements, Elena writes: 'I'm still unclear about the `user_details` endpoint. The OpenAPI spec shows an example response with nested arrays for 'interests' and 'skills', but it doesn't explain how these are structured or what data types they contain.' Considering this context, which option best describes Elena's issue?
Elena's message reveals she lacks understanding of the *structure* and *data types* within the nested arrays. The OpenAPI spec provides details about *what* fields exist, but not *how* they are organized or what kind of data they hold – a common misunderstanding when dealing with complex API responses.
24 / 26
"The OpenAPI spec for the `products` service provides examples that only show the basic product schema. However, I'm trying to build a dashboard that requires information about related categories and reviews, and the documentation doesn't provide any guidance on how these might be included in a full response. What is the primary issue highlighted by this statement?
This statement directly points out the lack of comprehensive examples. A good OpenAPI spec should demonstrate how related data (categories, reviews) might be included within a full response for the `products` endpoint – showing developers how to build real-world applications using the API.
25 / 26
During a standup meeting, David says: 'I'm working on integrating with the new `customer_data` API. The OpenAPI documentation provides individual examples for each field in the response, but it doesn't show how these fields are related to one another – like order history or shipping addresses. It makes understanding the complete customer record difficult.' What is David primarily complaining about regarding the API documentation?
David's core concern is the lack of context regarding relationships between fields. A complete `customer_data` response includes multiple related pieces of information (order history, shipping addresses). The OpenAPI spec needs to show how these elements connect to provide a holistic understanding – demonstrating a 'joined' view of the data.
26 / 26
"I'm reviewing this PR for the new `flights` API. The documentation specifies an 'example response' for the endpoint, but it's just a single JSON object with a limited set of fields. It doesn't show how to structure a request that includes multiple flight options or filters. What is the most relevant critique implied by this statement?
This critique highlights a key aspect of good API documentation: providing examples that demonstrate *request* structures alongside response formats. A robust OpenAPI spec should illustrate how to filter flight options, which is crucial for real-world usage and reflects the true functionality of the `flights` endpoint.
Frequently Asked Questions
What will I practice in "OpenAPI Examples Vocabulary Quiz"?
This is an API Spec Writing exercise set. It walks through 26 scenario-based multiple-choice questions built around real usage of API Spec Writing terminology that IT professionals encounter on the job.
Is this exercise free to use?
Yes. Every exercise on CoderSlingo, including this one, is free to complete with no account, sign-up, or paywall.
How many questions are in this exercise?
This set contains 26 questions. Each one shows immediate feedback and a detailed explanation after you answer, so you learn the correct usage right away rather than waiting for a final score.
Do I need prior experience to complete this exercise?
No prior experience is required. Each question includes a full explanation covering the reasoning behind the correct answer, so the exercise itself teaches the API Spec Writing vocabulary as you go.
Can I retry the exercise if I get questions wrong?
Yes — use the "Try again" button on the results screen to reset your answers and go through all the questions again. There is no limit on attempts.
Is my progress saved?
Your answers and score for the current session are tracked in the browser as you go. No account or login is needed, and there is nothing to install.
What if I don't understand a term used in a question?
Read the explanation shown after you answer each question — it breaks down the correct term in plain English with a real-world example. You can also check the site Glossary for quick definitions.
How is this different from reading a blog article on the topic?
Exercises like this one are interactive drills that test and reinforce specific vocabulary through multiple-choice questions, while blog articles explain concepts in prose. Practising here after reading builds active recall, not just passive recognition.
Where can I find more API Spec Writing exercises?
See the API Spec Writing exercises hub for the full set of related pages, or browse all exercise categories from the main Exercises index.
Can I use this exercise to prepare for a technical interview?
Yes — API Spec Writing vocabulary comes up often in technical discussions and interviews. Pair this exercise with our dedicated Interview Preparation section for role-specific practice.