Skip to content

OpenAPI contract checks

If your API has an OpenAPI description, Reqjet can check every response against it: that the status is documented, and that the body fits the schema. Name the description at the top of a .http file:

# @reqjet.openapi ./openapi.yaml
### Get a pet
GET {{baseUrl}}/pets/7
### List pets
GET {{baseUrl}}/pets?limit=10

The description can be JSON or YAML, OpenAPI 3 or Swagger 2. The path is relative to the .http file.

  1. The operation. The request is matched to an operation by its method and path template, allowing for the base paths of the description’s servers. A more specific path wins: /pets/mine beats /pets/{id}. A request with no matching operation fails.
  2. The status. It must be documented, exactly, as a range such as 4XX, or by default.
  3. The body. A JSON body must fit the response’s schema:
    • types and required properties;
    • properties that aren’t in the schema, when it says additionalProperties: false;
    • enum, nullable and array items;
    • allOf, anyOf and oneOf;
    • the date-time, date, uuid, email and uri formats.

Problems are listed by path, such as $.id should be an integer, but is a string.

The checks are tests like any other. They appear in the response’s Tests tab, as “openapi: GET /pets/{id}” and “openapi: body matches the schema”, and a failure fails a reqjet run in CI.

The same description can also drive the mock server: each operation gets a route that answers with its example.