Revision and Interview Questions

Cheat sheet

Basics: OpenAPI describes HTTP APIs in YAML/JSON; Swagger 2.0 became OpenAPI; Swagger now names tools (UI, Editor, Codegen); 3.1 aligns with JSON Schema 2020-12; AsyncAPI for events. Document: openapi, info (API version), servers, paths, webhooks, components, security, tags. Operations: methods under paths, unique operationId, summary, description, tags, deprecated. Parameters: in path (required), query, header, cookie; schema constraints; style/explode. Bodies and responses: requestBody.content by media type; responses keyed by status strings or ranges plus default; required description; headers such as Location and Retry-After; examples. Schemas: types, formats, required, constraints, readOnly/writeOnly, additionalProperties; $ref; allOf (extend), oneOf (exactly one, with discriminator), anyOf; 3.1 type: [string, 'null'] instead of nullable, examples arrays. Security: apiKey, http basic/bearer, oauth2 flows and scopes, openIdConnect, mutualTLS; global security, security: [] for public. Errors: Problem Details (RFC 9457), reusable responses. Design: cursor pagination, conventions, additive evolution, deprecation, breaking-change detection. Tooling: Swagger UI, Redoc, Spectral, Redocly, Prism, Schemathesis, OpenAPI Generator, springdoc-openapi (/v3/api-docs), FastAPI (/docs).

Common interview questions

Answer each with a short YAML example.

1. What is the difference between OpenAPI and Swagger?
2. Describe the top-level structure of an OpenAPI 3.1 document.
3. Design-first vs code-first: trade-offs and when to use each?
4. How do you describe path, query and header parameters? Which must be required?
5. How do readOnly and writeOnly change request and response schemas?
6. Explain allOf, oneOf and anyOf, and what a discriminator is for.
7. What changed between OpenAPI 3.0 and 3.1?
8. How do you document OAuth 2.0 scopes and make one endpoint public?
9. How would you describe errors consistently across an API?
10. Which changes are breaking, and how do you detect them automatically?
11. How do mock servers and contract tests use the OpenAPI document?
12. How would you generate client SDKs, and why should generated code not be hand-edited?

Bring a real document

If you have designed an API, mention a concrete decision encoded in its OpenAPI document, such as using cursor pagination or Problem Details errors, and why. Specific examples beat generic definitions.

Quick check: Which top-level field holds reusable schemas, parameters, responses and security schemes?

• paths
• info
• servers
• components