Swagger / OpenAPI

How QA uses Swagger and OpenAPI to read documentation, verify contracts, and establish API expectations.

Updated:

Contents

When someone tells QA to "check it in Swagger," they usually mean the interactive Swagger UI page. The underlying value is the machine-readable HTTP API description in OpenAPI format. It describes available operations, input parameters, responses, and data schemas. For testers, it is a starting point for contract testing. Attractive documentation does not establish that the service conforms to it, and the contract itself may be incomplete or outdated.

OpenAPI and Swagger tools

OpenAPI Specification is an API description standard. Swagger is a family of tools: Swagger UI displays the description and can execute requests, while editors help maintain the specification. The openapi field identifies the document format version; info.version identifies the described API's version. They differ: moving a document from standard 3.0 to 3.1 does not necessarily create a new business version of the service, and vice versa.

Reading an operation description

Start with the method and path, then inspect path/query/header parameters, requestBody, responses, and security requirements. Reusable schemas are usually in components. Examine required, length and range limits, allowed enum values, oneOf alternatives, and $ref references. Requiring a request body and requiring an individual property are defined at different levels. Reading only example JSON makes it easy to miss constraints that the example never demonstrates.

Schema version matters

As of October 2026, OpenAPI 3.2.1 has been published, although a project may have sound reasons to use another version. Check compatibility with validators, client generators, and the keywords used. For example, nullable representation rules differ between the 3.0 and 3.1 branches. Avoid changing syntax based on memory of an arbitrary guide. For reproducible analysis, preserve a specific specification version alongside the service build and validation results; a link to a constantly changing document soon loses value as evidence.

From schema to test data

Suppose POST /orders accepts quantity, an integer from 1 to 10, and sku, a nonempty string. The contract says successful creation returns 201 with id and quantity. This suggests checks for minimum and maximum values, adjacent invalid values, missing quantity, a string instead of a number, and missing sku. Business rules are also needed: whether the product exists, enough stock is available, and the user may place an order. Request structure does not automatically describe these conditions.

This small schema fragment illustrates the difference between declaring a field and requiring it. It is part of a document, rather than a complete specification for a finished API.

yaml
type: object
required:
  - sku
  - quantity
properties:
  sku:
    type: string
    minLength: 1
  quantity:
    type: integer
    minimum: 1
    maximum: 10

Exercise: checking an order contract

Start with a pinned specification file, a test environment, a user with the required role, and a product with enough stock. Suppose the requirements separately promise a validation error for an invalid quantity. Use isolated orders so stock changes do not affect other scenarios.

  1. 1.Send quantity=1 and quantity=10. Expect successful creation and responses matching the documented types and required properties.
  2. 2.Send 0, 11, 1.5, and the string "2" in separate requests. Derive expectations from the contract; if type coercion is allowed, a string is not necessarily a defect.
  3. 3.Remove quantity from the body. Expect the agreed missing-field error rather than an undocumented silent default.
  4. 4.Check the Content-Type header and error structure. Do not apply the successful response schema to an error response.
  5. 5.Retrieve the created order through another request. A valid creation response does not establish that the server saved correct data.

A security scheme does not replace permission testing

A bearerAuth description explains how to send credentials, but does not prove correct user isolation. Create an object under one token and try reading or changing it under another. Test a missing token, an insufficient role, and a revoked session. Within security, several schemes in one object are required together; separate objects in the array represent alternatives. Misinterpreting this changes test expectations, so consult the specification for the version in use.

What a documentation–service mismatch means

If the schema requires a string id but the server returns a number, record the discrepancy. Work with the API owner to establish the source of truth: is the implementation wrong, or the document? Avoid "fixing" the test simply by weakening it. When both artifacts are generated from the same code, they can consistently repeat the same error; independent requirements and consumer scenarios remain necessary. Formal validation is useful, but does not exhaust integration testing.

Also check the semantics of empty values: an absent property, an empty string, an empty array, and null may imply different actions. This is especially apparent in PATCH: an omitted field may mean "leave unchanged," while null means "clear," depending on the contract. Prepare an existing object with known values, test each form separately, and retrieve the result. The schema helps determine valid input; the requirements explain state changes. If the description does not answer this question, record the gap before defining a test expectation. Resolving ambiguity is more useful than arguing over which response feels familiar to an individual tester.

Compatibility and contract changes

Removing a field, narrowing an enum, adding a required parameter, or changing a type often breaks clients. Even an added field should be assessed against consumer strictness. Compare specification versions during review and test critical clients separately. For an optional field, check an older client's behavior without it; for a deprecated operation, check the agreed transition schedule and path. One successful call to the new version does not establish backward compatibility for the entire integration.

Common mistakes and practical takeaways

Common mistakes include testing only examples, confusing required with properties, assuming the execution button is safe against any server, and opening an internal specification in an external service without checking its contents. Swagger UI sends real requests and depends on the browser environment, including CORS. Good QA work produces contract checks, separately identified business risks, and verified discrepancies. The document becomes a working agreement between teams when checked against the real service.

Further reading