Top 30 Swagger and OpenAPI Interview Questions and Answers [2026]

TL;DR: Swagger and OpenAPI interviews in 2026 test schema design, reuse with $ref and components, security schemes, and a spec-first workflow with linting and breaking-change checks in CI. Candidates should know OpenAPI 3.1's switch to full JSON Schema, and what OpenAPI 3.2 adds for streaming and the new QUERY method.

The OpenAPI Initiative released OpenAPI 3.2.1 on September 10, 2026, a clarification release for 3.2.0 from a year earlier.

Version 3.2 added nested tags, server-sent event streams and the HTTP QUERY method, which the IETF published as RFC 10008 in June 2026.

Interviewers now ask what changed in 3.1 and 3.2, because each upgrade touches every tool that reads the description.

OpenAPI Basics

1. What is the difference between Swagger and OpenAPI?

OpenAPI is the specification; Swagger is a family of tools from SmartBear, such as Swagger UI, Swagger Editor and Swagger Codegen. The spec started as the Swagger Specification.

SmartBear donated Swagger 2.0 in 2015, and it became the OpenAPI Specification, run by the OpenAPI Initiative.

So "Swagger 2.0" and "OpenAPI 2.0" are the same format. From version 3.0 on, the right name for the format is OpenAPI.

2. What are the main parts of an OpenAPI document?

An OpenAPI document declares its version, describes the API, and lists its operations and reusable parts. The main top-level fields:

• openapi: the spec version, such as 3.1.1.
• info: title, version of the API, contact and license.
• servers: base URLs.
• paths: each path and its operations (get, post and so on).
• webhooks (3.1 and later): requests the API sends to consumers.
• components: reusable schemas, parameters, responses and security schemes.
• security and tags: default auth rules and grouping.

In 3.1, a description must contain at least one of paths, components or webhooks. A file of shared schemas with no paths is now valid.

3. What changed from Swagger 2.0 to OpenAPI 3.0?

OpenAPI 3.0 reorganized reuse and request bodies. The main changes:

• definitions, parameters and securityDefinitions moved under one components object.
• body and formData parameters became a requestBody with one entry per media type.
• host, basePath and schemes became a servers list with variables.
• New callbacks and links, and oneOf/anyOf support in schemas.
• OpenID Connect and HTTP bearer security schemes.

4. What changed from OpenAPI 3.0 to 3.1?

OpenAPI 3.1 made the Schema Object fully compatible with JSON Schema Draft 2020-12. The 3.0 schema was a modified subset of an older draft, which confused tools and users. The upgrade guide lists the breaking changes, all in schemas:

• nullable: true is gone. Use a type array: type: ["string", "null"].
• exclusiveMinimum and exclusiveMaximum take a number, not a boolean.
• Schema example becomes examples, an array.
• File content uses contentMediaType and contentEncoding instead of format: binary or format: byte.

3.1 also added top-level webhooks, and JSON Schema features such as if/then/else and $schema to declare a dialect.

# OpenAPI 3.0
type: string
nullable: true

# OpenAPI 3.1
type: [string, "null"]

5. Design-first or code-first: which do you prefer, and why?

Design-first means writing the OpenAPI description before the code; code-first means generating it from annotations in the code.

Design-first suits public and cross-team APIs, where the contract must be agreed before anyone builds against it.

With design-first, front-end and back-end teams can work in parallel against a mock server. Reviews happen on a readable spec, not scattered annotations.

Code-first is faster for internal APIs with one consumer, and the spec cannot drift from the code. The risk is a spec that is technically accurate but poorly described, because nobody reviewed it as a design.

Many teams mix them: design-first for the contract, then a CI check that the running code still matches it.

6. How do you keep a large OpenAPI description maintainable?

Split it into files by path and component, reference them with $ref, and bundle them into one file for tools that need it.

paths:
  /orders:
    $ref: "./paths/orders.yaml"
components:
  schemas:
    Order:
      $ref: "./schemas/Order.yaml"

A bundler such as Redocly CLI (redocly bundle) resolves the references into one document for publishing or code generation. Consistent naming, a shared schema library across APIs, and linting keep a large set of files readable.

Schemas and Reuse

7. What is the components object, and how does $ref work?

components holds reusable definitions, and $ref points to them by URI. Reusable types include schemas, responses, parameters, examples, requestBodies, headers, securitySchemes, links, callbacks and pathItems. Version 3.2 adds mediaTypes.

A reference such as $ref: "#/components/schemas/User" is a JSON Pointer within the same document. It can also point to another file or URL.

In 3.1, a Reference Object may carry its own summary and description, which override the target's. Inside schemas, $ref follows JSON Schema rules and can sit next to other keywords.

8. How do oneOf, anyOf and allOf differ?

oneOf requires the data to match exactly one subschema, anyOf at least one, and allOf all of them.

• oneOf: mutually exclusive shapes, such as a card payment or a bank payment.
• anyOf: overlapping options, such as a contact that may have an email, a phone or both.
• allOf: composition, such as a Dog that is a Pet plus its own fields.

A common oneOf bug is two subschemas that both accept the same object, for example because neither sets additionalProperties: false or a distinguishing required field. The data then matches both and fails validation.

9. What does the discriminator do?

The discriminator names a property whose value tells tools which subschema applies. It speeds up validation and helps code generators produce the right class.

Payment:
  oneOf:
    - $ref: "#/components/schemas/CardPayment"
    - $ref: "#/components/schemas/BankPayment"
  discriminator:
    propertyName: method
    mapping:
      card: "#/components/schemas/CardPayment"
      bank: "#/components/schemas/BankPayment"

It is a hint, not a validation rule: the oneOf still does the validating. OpenAPI 3.2 made propertyName optional and added defaultMapping, which picks a schema when the property is missing or has an unknown value.

10. How do you describe a file upload in OpenAPI 3.1?

Use multipart/form-data for a file sent with other fields, and describe the file with contentMediaType. For a raw binary body, a media type with no schema is enough.

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          orderId:
            type: integer
          invoice:
            type: string
            contentMediaType: application/pdf

This replaces 3.0's type: string, format: binary. For base64 text inside JSON, use contentEncoding: base64 rather than 3.0's format: byte.

11. What is the difference between format and pattern?

pattern is a regular expression the string must match; format names a known kind of value, such as date-time, email or uuid.

Under JSON Schema 2020-12, which OpenAPI 3.1 uses, format is an annotation by default. Many validators do not enforce it unless configured to.

So if a value must be checked, add a pattern, a maxLength or both, or turn on format assertion in your validator and test that it works.

12. How do readOnly and writeOnly work?

readOnly: true marks a property that appears in responses but should not be sent in requests, such as id or createdAt. writeOnly: true marks one that is sent but never returned, such as password.

They let one schema serve both directions. In 3.1 they are JSON Schema annotations, not hard rules, and the 3.1.1 spec says a server MAY ignore a readOnly field in a request or treat it as an error.

A field that is both required and readOnly is required in a GET response, and the server can ignore it in a PUT. Tools handle this differently, so teams with strict clients often use separate request and response schemas.

Operations and Security

13. How are parameters serialized, and what do style and explode do?

Each parameter has a location (path, query, header or cookie), and style plus explode decide how arrays and objects are written into it.

The defaults are form style with explode: true for query and cookie, and simple for path and header. So an array ids = [1, 2] in the query becomes ?ids=1&ids=2 by default. With explode: false it becomes ?ids=1,2.

Path parameters must be required: true. OpenAPI 3.2 adds a querystring location that describes the whole query string as one value.

14. What is the difference between securitySchemes and security?

components.securitySchemes defines the ways a client can authenticate; security says which of them apply, to the whole API or one operation.

security:
  - oauth: [orders:read]      # option 1: OAuth with this scope
  - apiKey: []                # OR option 2: an API key
  - mtls: []
    apiKey: []                # OR option 3: mTLS AND an API key

Items in the list are alternatives (OR). Schemes inside one item must all be satisfied (AND). An empty item, {}, makes authentication optional.

An operation's own security replaces the top-level one; security: [] removes it for that operation.

15. How do you describe OAuth 2.0 and OpenID Connect?

Use a scheme of type: oauth2 with one entry per flow, each listing its URLs and scopes. For OpenID Connect, use type: openIdConnect with an openIdConnectUrl pointing at the discovery document.

components:
  securitySchemes:
    oauth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          scopes:
            orders:read: Read orders
            orders:write: Create and change orders

The spec only documents the scheme. It does not enforce it, so the API or gateway must still validate tokens. OpenAPI 3.2 adds the device authorization flow and an oauth2MetadataUrl for the server's RFC 8414 metadata.

16. What is the difference between callbacks and webhooks?

A callback is a request the API sends back to a URL that the client gave in an earlier call. A webhook, added as a top-level field in 3.1, is a request the API sends that does not depend on a specific earlier call.

Use a callback for "call this URL when the export you started is ready", where the URL arrives in the request body. Use webhooks for events that consumers register for separately, such as orderShipped.

Both are described as Path Item Objects, from the consumer's side.

17. What is the links object for?

links describes how a value in one response can feed a later request, such as using the id from POST /orders as orderId in GET /orders/{orderId}.

It is design-time documentation for tools and readers. It is not runtime hypermedia: nothing is added to the actual response, so it does not make an API HATEOAS-compliant.

Few tools use links today, and Arazzo, covered below, handles multi-step flows more fully.

Tooling and CI

18. What does an API linter check, and where does it run?

A linter checks a description against rules: valid structure, plus your own style guide. Spectral and Redocly CLI are the common open-source choices.

Typical custom rules: every operation has an operationId and a description, paths use kebab-case, every operation declares security, and every 4xx or 5xx response uses the shared error schema.

It runs in the editor for fast feedback, and in CI on every pull request so a rule break blocks the merge.

19. How do you catch breaking changes in an API?

Compare the new description against the last released one in CI, and fail the build on changes that break existing clients.

Breaking changes include removing an operation or a response field, adding a required request field or parameter, narrowing a type or enum, and changing auth requirements. Adding an optional field or a new endpoint is usually safe.

Tools such as oasdiff automate the comparison. The check only works if the description matches the running code, which is why teams pair it with response validation in tests.

20. What are the pros and cons of generating code from OpenAPI?

Generation gives typed clients and server stubs that match the contract, in many languages, with little effort. The cost is code you do not fully control.

• Pros: no hand-written models, clients update when the spec changes, and one spec serves many languages.
• Cons: output can be non-idiomatic, complex oneOf and allOf models often generate poorly, and custom templates are work to maintain.

The main open-source generator is OpenAPI Generator, a community fork of Swagger Codegen. Pin its version in CI, because template changes between releases can change generated code.

21. How does OpenAPI support contract testing?

The description is the contract, so tests can check real requests and responses against it. There are three common forms:

• Response validation: integration tests assert that every response matches the schema for its status code.
• Request validation middleware: the server rejects requests that do not match the spec, before the handler runs.
• Property-based fuzzing: tools such as Schemathesis generate requests from the spec to find crashes and schema violations.

Consumer-driven contract tests, such as Pact, cover a different gap: they check what each consumer actually uses, not only what the provider declares.

22. How do mock servers fit into a design-first workflow?

A mock server answers requests using the examples and schemas in the description, before the real API exists. Front-end and partner teams can start building on day one.

Mocks are only as good as the examples. Give each response realistic examples, including error cases, and lint for missing ones. Prism, from Stoplight, is a widely used open-source mock server.

23. How do you handle versioning in OpenAPI?

Keep info.version for the version of the description, and put the API's major version where clients see it: usually the path (/v2/orders) or a server URL.

Each major version normally gets its own description file.

Within a major version, only add backward-compatible changes, and mark old operations, parameters or schema properties with deprecated: true before removing them in the next major version.

Do not confuse info.version with the openapi field, which is the spec version.

24. When would you use AsyncAPI or gRPC instead of OpenAPI?

Use OpenAPI for request-response HTTP APIs, AsyncAPI for event-driven APIs over brokers such as Kafka or MQTT, and Protocol Buffers with gRPC for fast internal RPC.

OpenAPI 3.2's streaming support narrows the gap for server-sent events, but a system built around a message broker still fits AsyncAPI better.

What Changed Recently

25. What are the headline features of OpenAPI 3.2?

According to the 3.2.0 release notes, the main additions are:

• Tags with nesting: new summary, parent and kind fields.
• More HTTP methods: a query operation, plus additionalOperations for any other method.
• Streaming: sequential media types such as text/event-stream and application/jsonl, with itemSchema.
• A querystring parameter location and a $self field for the document's base URI.
• Security: the OAuth device flow, oauth2MetadataUrl, and deprecated on security schemes.

The OpenAPI Initiative says it keeps "full backward compatibility with OpenAPI 3.1", so upgrading means changing the openapi field and then adopting features as needed. The 3.1 to 3.2 upgrade guide walks through it.

26. How do you describe a server-sent events stream in OpenAPI 3.2?

Use the text/event-stream media type with itemSchema, which describes each event rather than the whole response. The response is treated as a sequence of items.

responses:
  "200":
    description: Token stream
    content:
      text/event-stream:
        itemSchema:
          type: object
          properties:
            event: { type: string }
            data: { type: string }
          required: [data]

Before 3.2 there was no standard way to say what each event looks like, which mattered as LLM APIs made streaming responses common. The same pattern covers application/jsonl and application/json-seq.

27. What is the HTTP QUERY method, and how does OpenAPI 3.2 support it?

QUERY is a safe, idempotent method that carries its query in the request body. It suits searches too complex for a URL. The IETF published it as RFC 10008 in June 2026.

Teams used to choose between a GET with a very long query string and a POST /search that caches and retries poorly because POST is not idempotent. QUERY has the body of a POST with the safety of a GET.

OpenAPI 3.2 adds a query field on the Path Item, next to get and post. Check that your gateway, proxies and client libraries pass the method through before relying on it.

28. What is Arazzo?

Arazzo describes workflows that span several API calls, such as "create a cart, add items, check out". Each step names an operation from an OpenAPI description, its inputs, and success criteria. Outputs from one step feed later steps.

It suits executable API tests, onboarding docs, and giving AI agents a known sequence of calls to follow. Arazzo 1.1.0 (May 2026) added support for AsyncAPI 3 steps, JSONPath and XPath selectors, and OpenAPI 3.2's querystring.

See the Arazzo spec.

29. What is an Overlay, and when do you use one?

An Overlay is a separate document of actions that update or remove parts of an OpenAPI description, targeted with JSONPath. It lets you change a description without editing the source.

Common uses are adding docs-only descriptions to a generated spec, removing internal endpoints before publishing, and adding vendor extensions for one tool. Overlay 1.1 (January 2026) added a copy action and RFC 9535 JSONPath compliance.

Overlay 1.2 (September 2026) added reusable actions under components.actions.

30. Should a team upgrade to OpenAPI 3.1 or 3.2 today?

Check the tools first, because a description is only as useful as the tools that read it. Moving from 3.0 to 3.1 has breaking schema changes; moving from 3.1 to 3.2 does not.

Swagger UI has supported 3.1 since v5.0.0 in 2023 and added basic 3.2 support in v5.32.0. List every tool in the pipeline, including the linter, generator, gateway import, mock server and docs renderer, and test each on a converted copy.

A strong answer names a blocker the candidate actually hit, such as a generator that mishandled type arrays.

Signs of a Strong Answer

• They say "OpenAPI" for the spec and "Swagger" for the tools, and know which version their team writes.
• They convert nullable and format: binary to 3.1 style without looking it up.
• They explain the OR and AND rules of security, including how to make auth optional.
• They run linting and breaking-change checks in CI, and can name a rule they wrote.
• They treat the discriminator as a hint and know when oneOf matches twice.
• They know what 3.2 adds for streaming and QUERY, and check tool support before adopting it.

Hiring API Developers

A clear API contract saves every team that builds on it, so API design deserves engineers who have written and maintained real specs.

Second Talent matches companies with pre-vetted API developers from Asia, screened with questions like these.

Tell us the stack and we send a shortlist within 24 hours. Start hiring, or see our API gateway and API security interview guides.