ASP.NET Core Web API Interview Question #96

How can API examples improve OpenAPI documentation?

Routing, Versioning, OpenAPI/Swagger & API Documentation Mid-Level Intermediate

Quick Interview Answer

Examples show clients realistic request and response payloads in addition to schemas. They can clarify formatting, optional fields, enums, error contracts, and typical values.

Detailed Explanation

Examples show clients realistic request and response payloads in addition to schemas. They can clarify formatting, optional fields, enums, error contracts, and typical values.

Examples should remain synchronized with the actual API contract. Misleading examples can be worse than no examples because developers often copy them directly into integrations.

Code Example

{
  "id": 42,
  "name": "Wireless Mouse",
  "price": 29.99,
  "category": "Accessories"
}