API / Swagger Interview questions
1. What is Swagger?
Swagger is a set of open-source tools built around describing, documenting, and testing REST APIs using a standardized, machine-readable format — originally its own specification, which later became the foundation for the OpenAPI Specification. The Swagger toolset today centers on three mai...
2. What is the purpose of Swagger?
Swagger's core purpose is to make API documentation a byproduct of a structured, machine-readable definition rather than a manually written document that has to be kept in sync by hand every time the API changes. Because the definition describes every endpoint, parameter, request body, and respon...
3. What is the OpenAPI Specification?
The OpenAPI Specification (OAS) is the formal, vendor-neutral standard for describing REST APIs — endpoints, operations, parameters, request/response schemas, authentication methods — in a language-agnostic format, maintained by the OpenAPI Initiative under the Linux Foundation. It ev...
4. What is the difference between Swagger and OpenAPI?
These terms are often used interchangeably in casual conversation, but they refer to two related, distinct things: OpenAPI is the specification (the standard itself), while Swagger is the brand name attached to a specific set of tools built to work with that specification. OpenAPI Swagger The ope...
5. What are the key components of Swagger?
The Swagger toolset is built from a small number of complementary tools, each covering a different stage of working with an OpenAPI document. Tool Purpose Swagger Editor Browser-based or local editor for writing and live-validating OpenAPI YAML/JSON Swagger UI Renders an OpenAPI document as inter...
6. What is Swagger UI?
Swagger UI is a tool that takes any valid OpenAPI document and renders it as an interactive documentation website, without requiring the API team to write a separate documentation page by hand or keep two sources of truth synchronized. Beyond just displaying endpoints and their parameters, Swagge...
7. What is Swagger Editor?
Swagger Editor is a dedicated editor for writing OpenAPI documents in YAML or JSON, available both as a hosted web app and as a tool that can be run locally, offering live validation and a real-time preview pane rendered by Swagger UI as you type. As you edit the definition, the editor highlights...
8. What is Swagger Codegen?
Swagger Codegen is a code generation tool that reads an OpenAPI document and produces client-side SDK code, or server-side stub/skeleton code, in any of dozens of supported programming languages, based on templates for each target language. swagger-codegen generate \ -i openapi.yaml \ -l java \ -...
9. Define paths in an OpenAPI document?
The paths object is the section of an OpenAPI document that enumerates every available endpoint (URL template) in the API, and for each one, which HTTP methods (operations) it supports. paths: /users/{userId}: get: summary: Get a user by ID parameters: - name: userId in: path required: true schem...
10. What are operations in OpenAPI?
An operation is a single, specific combination of an HTTP method and a path — for example, GET /users/{userId} is one operation, and POST /users is a different operation, even though both live under paths that might share a common prefix. Each operation object can define its own summary and...
11. What is a schema in OpenAPI?
A schema is a description of the shape and constraints of a piece of JSON (or other media type) data — the fields an object has, their types, which are required, and validation rules like string formats or numeric ranges — used throughout an OpenAPI document to describe request bodies...
12. What are the supported formats for writing an OpenAPI document?
An OpenAPI document can be written in either YAML or JSON, and both are fully equivalent — tooling that consumes OpenAPI documents (Swagger UI, code generators, validators) accepts either format interchangeably, since JSON is itself a valid subset of YAML's data model. YAML JSON More concis...
13. What is the purpose of the info object in OpenAPI?
The info object holds metadata that describes the API as a whole, rather than any specific endpoint — its title, version, description, contact information, and license — and it's a required top-level field in every valid OpenAPI document. info: title: Bookstore API description: Manage...
14. What are tags used for in Swagger?
Tags let you group related operations together for organizational purposes in the rendered documentation, so instead of Swagger UI showing one long, flat list of every endpoint in the API, operations are clustered under headings like "Users," "Orders," or "Payments." paths: /users: get: tags: [Us...
15. List the HTTP methods supported in OpenAPI operations?
OpenAPI supports describing operations for all the standard HTTP methods a REST API might use under a given path, each represented as its own key nested under that path in the specification. Method Typical Use get Retrieve a resource or collection without side effects post Create a new resource, ...
16. What is a parameter in OpenAPI, and what are its types?
A parameter is an input to an operation supplied outside the request body — part of the URL, headers, or query string — and OpenAPI defines exactly where each parameter is expected using its in field. Type (in) Location path Part of the URL path itself, e.g. /users/{id} query Appended...
17. What is a response object in OpenAPI?
A response object describes what an operation returns for a specific HTTP status code — its description, headers, and the schema of its body content — and every operation's responses field maps possible status codes to these descriptions. responses: '200': description: Successful retr...
18. Describe the components section in OpenAPI 3.0?
The components object is where reusable pieces of an OpenAPI document live — schemas, parameters, responses, request bodies, security schemes, and examples — so they can be defined once and referenced from many places via $ref instead of duplicated. components: schemas: User: type: ob...
19. What is $ref used for in OpenAPI documents?
$ref is a JSON Reference pointer that lets one part of an OpenAPI document point to a definition located elsewhere, most commonly a reusable schema, parameter, or response defined under components , avoiding duplication of the same structure in multiple places. paths: /users/{id}: get: responses:...
20. How do you use Swagger annotations in a Java Spring Boot application?
In a Spring Boot application, Swagger/OpenAPI documentation is typically generated automatically from annotated controller code using a library like springdoc-openapi, rather than hand-writing the YAML/JSON spec separately and keeping it in sync manually. @RestController @RequestMapping ( "/users...
21. What is the difference between OpenAPI 2.0 (Swagger) and OpenAPI 3.0?
OpenAPI 3.0 was a significant restructuring of the specification compared to its predecessor, Swagger 2.0, introducing several structural changes aimed at improving flexibility and reducing duplication. Swagger 2.0 OpenAPI 3.0 Single host/basePath/schemes fields for server info. A servers array, ...
22. What is the difference between OpenAPI 3.0 and OpenAPI 3.1?
OpenAPI 3.1, released after 3.0, focused primarily on aligning the specification's schema syntax much more closely with standard JSON Schema, resolving long-standing incompatibilities that had made some valid JSON Schema constructs unusable in earlier OpenAPI versions. OpenAPI 3.0 OpenAPI 3.1 Sch...
23. Why is contract-first API design preferred over code-first in some teams?
Contract-first means writing the OpenAPI specification before writing any implementation code, then generating server stubs and client SDKs from that agreed-upon contract; code-first means writing the implementation first and generating the OpenAPI document from annotations on that code afterward...
24. How does Swagger support security schemes like OAuth2 and API keys?
OpenAPI describes authentication mechanisms through securitySchemes defined under components , and then references those schemes — either globally or per-operation — via a security field, so tools like Swagger UI know how to prompt for and attach credentials when testing an endpoint. ...
25. What is the difference between springfox and springdoc-openapi?
Both are Java libraries that generate an OpenAPI document automatically from annotated Spring controllers, but they target different specification versions and have very different current maintenance status. springfox springdoc-openapi Generates Swagger 2.0 documents by default. Generates OpenAPI...
26. How do you document request and response examples in OpenAPI?
OpenAPI lets you attach concrete example values to a schema, parameter, request body, or response, giving consumers a realistic sample of actual data alongside the abstract type/shape description — useful because a schema alone doesn't always convey what "realistic" values actually look lik...
27. Explain how Swagger Codegen generates client SDKs from an OpenAPI spec?
Swagger Codegen (and its successor, OpenAPI Generator) works by parsing an OpenAPI document into an internal model, then feeding that model through a set of language-specific Mustache templates that produce the actual source code files for the target language. flowchart TD A[OpenAPI document] -->...
28. What is the difference between path parameters and query parameters?
Both types of parameters pass input into an operation, but they differ in where they live in the URL and, as a consequence, in what kind of data they're suited for describing. Path Parameter Query Parameter Embedded in the URL path: /orders/{orderId} Appended after ?: /orders?status=shipped Alway...
29. How do you handle polymorphism and discriminators in OpenAPI schemas?
OpenAPI describes polymorphic schemas — where a field could hold one of several different possible object shapes — using the oneOf keyword combined with a discriminator , which tells consuming tools which specific field in the payload determines which of the possible schemas actually ...
30. Explain the lifecycle of validating an OpenAPI document with a linter like Spectral?
A linter like Spectral checks an OpenAPI document against a configurable rule set — both structural correctness against the specification itself and style/best-practice rules a team defines — and reports violations before the document is ever published or consumed downstream. flowchar...
31. When should you use the allOf, oneOf, and anyOf keywords in OpenAPI schemas?
These three keywords all combine multiple schemas, but they express different logical relationships between them, and picking the wrong one produces validation behavior that doesn't match the intended data shape. Keyword Meaning Typical Use allOf Data must satisfy every listed schema Composing/ex...
32. How do you version a REST API documented with Swagger?
OpenAPI itself doesn't prescribe one specific API versioning strategy — that's an API design decision separate from the documentation format — but whichever strategy is chosen needs to be reflected consistently in the spec so the documentation matches actual API behavior. Strategy How...
33. What happens when you click "Try it out" in Swagger UI?
Clicking "Try it out" switches an operation's documentation from a read-only display into an interactive form: input fields appear for every declared parameter and request body field, pre-filled with any example values from the spec, and an "Execute" button becomes available. Swagger UI collects ...
34. How do you split a large OpenAPI specification across multiple files?
Large specs are commonly split into multiple files — often one file per resource or domain area — connected back together using $ref pointers that reference definitions in other files rather than requiring every schema and path to live in one enormous document. # main openapi.yaml pat...
35. Explain the internal working of Swagger UI's rendering process?
Swagger UI is a client-side JavaScript application that fetches an OpenAPI document (as JSON, or YAML converted to JSON) and dynamically builds its entire interface from that document's structure, rather than shipping any pre-built, endpoint-specific HTML. flowchart TD A[Browser loads Swagger UI ...
36. How do you mock an API server using an OpenAPI specification?
Because an OpenAPI document already fully describes every endpoint's expected request and response shapes, a mock server can be generated directly from it — returning example or schema-generated responses for each operation — without any real backend logic behind it, which is especial...
37. What is the difference between Swagger and Postman?
Both tools are commonly used around REST APIs, but they solve different core problems: Swagger/OpenAPI is fundamentally a specification format and documentation-generation toolset, while Postman is primarily an API client and manual/automated testing tool. Swagger / OpenAPI Postman A specificatio...
38. How do you deprecate an API operation in OpenAPI?
OpenAPI supports a simple boolean deprecated field that can be set on an individual operation (or on a whole schema, parameter, or property) to signal that it's still functional but shouldn't be used for new development, without removing it from the spec entirely while consumers migrate away. pat...
39. Explain the execution flow of generating server stubs from an OpenAPI document?
Server stub generation mirrors client SDK generation in mechanism — parsing the spec, mapping schemas to types, applying language/framework-specific templates — but the output is routing and controller scaffolding rather than an API-calling client. flowchart TD A[OpenAPI document] -->...
40. What is the difference between Swagger 2.0's definitions and OpenAPI 3.0's components/schemas?
Both serve the same fundamental purpose — a place to define reusable data shapes referenced elsewhere via $ref — but OpenAPI 3.0 relocated and reorganized this concept as part of its broader restructuring into the unified components object. # Swagger 2.0 definitions: User: type: objec...
41. How does content negotiation work in OpenAPI, using the content field?
OpenAPI 3.0's content field lets a single request body or response describe different schemas for different media types, mirroring how real HTTP content negotiation (via Accept and Content-Type headers) allows the same logical resource to be represented differently depending on what the client re...
42. Why doesn't OpenAPI natively describe webhooks before version 3.1?
Prior to OpenAPI 3.1, the specification's paths object was designed entirely around describing endpoints the API provider exposes for consumers to call — there was no structural equivalent for describing calls that flow in the opposite direction, where the API provider calls out to a URL th...
43. How do you handle authentication in Swagger UI for testing secured endpoints?
Swagger UI provides a global "Authorize" button (rendered whenever the spec defines one or more securitySchemes ) that opens a dialog for entering credentials matching each declared scheme, and those credentials are then automatically attached to every subsequent "Try it out" request that require...
44. What is the difference between OpenAPI Generator and the legacy Swagger Codegen?
OpenAPI Generator is a community-driven fork of the original Swagger Codegen project, created after disagreements over release cadence and OpenAPI 3.0 support timelines within the original project's governance, and it has since become the more actively maintained and widely adopted of the two. Sw...
45. Explain how to enforce validation constraints in an OpenAPI schema?
OpenAPI schemas support a range of validation keywords, inherited from JSON Schema, that go beyond simply declaring a field's type — letting a spec express constraints like string length, numeric ranges, and allowed value sets that a validating tool can check requests and responses against....
46. How do you convert a Swagger 2.0 document to OpenAPI 3.0?
Converting between the two versions is largely a mechanical, structural transformation, and dedicated conversion tools handle the bulk of it automatically, though the result usually still benefits from a manual review pass afterward. # Using the swagger2openapi CLI tool npx swagger2openapi swagge...
47. What is the role of the servers object in OpenAPI 3.0?
The servers array declares the base URL(s) where the described API can actually be reached, replacing Swagger 2.0's more limited single host / basePath / schemes combination with something that can describe multiple environments and even templated, variable URL segments in one place. servers: - u...
48. Explain the internal working of $ref resolution across multiple OpenAPI files?
When a tool encounters a $ref pointing outside the current file, it has to locate and load the referenced file, navigate to the specific fragment within it, and substitute that fragment in place of the reference — a process called dereferencing, or "bundling" when the goal is producing one ...
49. How do you implement contract testing using an OpenAPI specification?
Contract testing using OpenAPI validates that both a provider's real implementation and a consumer's actual usage genuinely conform to the shared, documented contract, catching drift between what the spec says and what the API (or its callers) actually does in practice. Provider-side validation: ...
50. Explain the execution flow of API documentation generation in a CI/CD pipeline using Swagger/OpenAPI tooling?
A mature CI/CD pipeline treats the OpenAPI document as a build artifact in its own right, validating, testing, and publishing it alongside the application code rather than as a manual, disconnected side task someone remembers to do occasionally. flowchart TD A[Code/spec change pushed] --> B{Spec ...
