OpenAPI: formerly Swagger, it is a machine-readable contract describing endpoints, parameters, request/response schemas, authentication, and examples. It enables documentation, code generation, and mock servers from one source of truth.
2 / 5
What is a $ref in an OpenAPI document?
$ref:$ref: '#/components/schemas/Error' includes the Error schema inline. Centralizing schemas in components ensures consistency — change a schema once and all references update.
3 / 5
What does the operationId field provide?
operationId: tools like OpenAPI Generator use this string as the method name in generated SDKs. A clear, consistent naming convention (e.g., getOrderById) makes generated code readable.
4 / 5
What is the purpose of discriminator in OpenAPI schemas?
Discriminator: when a field (e.g., type) determines which schema variant applies, the discriminator tells tools how to map the value to the correct schema, enabling proper validation and code generation for polymorphic payloads.
5 / 5
What does marking a parameter or field as deprecated: true communicate?
deprecated: generators may emit warnings; documentation tools display a strikethrough. It is part of a graceful API evolution strategy: announce deprecation, maintain the field for a version, then remove it.