Practice writing clear OpenAPI/Swagger documentation: operation summaries, parameter descriptions, response descriptions, and schema property documentation.
0 / 8 completed
1 / 8
What is the difference between 'summary' and 'description' in an OpenAPI operation?
OpenAPI summary (max 120 chars) appears in tooling lists and navigation. Description supports Markdown and is used for detailed documentation: business rules, rate limits, authentication notes, and examples.
2 / 8
Which is the best OpenAPI operation summary?
Good OpenAPI summaries are concise (under 10 words), use verb phrases, and describe the outcome. 'Returns the authenticated user's profile data' is clear, specific, and action-oriented.
3 / 8
How should a required path parameter be documented?
Parameter descriptions should include: what it identifies, format constraints, and an example. This prevents consumer errors and reduces support questions about unexpected 400 errors.
4 / 8
What should a '200 OK' response description include?
Response descriptions should describe what is returned and any notable fields. 'Success' tells consumers nothing useful. Developers reading the docs need to know exactly what to expect in the response body.
5 / 8
What is the recommended way to document an API error response (e.g., 400)?
Error response documentation should explain when this status occurs and common causes. This enables API consumers to write better error handling and reduces 'why am I getting a 400?' support tickets.
6 / 8
How should you document a schema property that has a specific allowed set of values?
Documenting enum values with their meaning is essential. '"pending"' without explanation leaves consumers guessing. Describing what each state means prevents incorrect state machine handling in client code.
7 / 8
What is the purpose of 'example' values in OpenAPI schema documentation?
Examples dramatically improve API documentation usability. A realistic example like 'email: user@example.com' or 'createdAt: 2024-01-15T10:30:00Z' is immediately clear, while 'email: string' or 'createdAt: ISO 8601 date' is abstract.
8 / 8
What does 'nullable: true' communicate in an OpenAPI schema property?
Nullable and optional are different: optional means you can omit the field; nullable means you can set it to null. A 'completedAt' timestamp might be nullable (null = not yet completed) but not optional (always present in the response).