OpenapiContracts

Use OpenAPI documentation as an API contract.

Currently supports OpenAPI documentation in the structure as used by Redocly, but should also work for single file schemas.

Adds RSpec matchers to easily verify that your requests and responses match the OpenAPI documentation.

Usage

First, parse your API documentation:

# This must point to the folder where the OAS file is stored
$doc = OpenapiContracts::Doc.parse(Rails.root.join('spec/fixtures/openapi/api-docs'), '<filename>')

In case the filename argument is not set, parser will by default search for the file named openapi.yaml.

Ideally you do this once in an RSpec before(:suite) hook. Then you can use these matchers in your request specs:

subject { make_request and response }

let(:make_request) { get '/some/path' }

it { is_expected.to match_openapi_doc($doc) }

You can assert a specific http status to make sure the response is of the right status:

it { is_expected.to match_openapi_doc($doc).with_http_status(:ok) }

# This is equal to
it 'responds with 200 and matches the doc' do
  expect(subject).to have_http_status(:ok)
  expect(subject).to match_openapi_doc($doc)
end

Options

The match_openapi_doc($doc) method allows passing options as a 2nd argument.

• path allows overriding the default request.path lookup in case it does not find the correct response definition in your schema. This is especially important when there are dynamic parameters in the path and the matcher fails to resolve the request path to an endpoint in the OAS file.

it { is_expected.to match_openapi_doc($doc, path: '/messages/{id}').with_http_status(:ok) }

• request_body can be set to true in case the validation of the request body against the OpenAPI requestBody schema is required.

it { is_expected.to match_openapi_doc($doc, request_body: true).with_http_status(:created) }

• parameters can be set to true to validate request parameters against the parameter definitions

it { is_expected.to match_openapi_doc($doc, parameters: true) }

Both options can as well be used simultaneously.

Without RSpec

You can also use the Validator directly:

# Let's raise an error if the response does not match
result = OpenapiContracts.match($doc, response, options = {})
raise result.errors.merge("/n") unless result.valid?

Coverage reporting

You can generate a coverage report, giving an indication how many of your OpenApi operations and responses are verified.

To enable the report, set the configuration OpenapiContracts.collect_coverage = true.

After the tests completed, you can generate the JSON file, for example:

RSpec.configure do |c|
  c.after(:suite) do
    $your_api_doc.coverage.report.generate(Rails.root.join("openapi_coverage.json"))
  end
end

In case you run tests on multiple nodes and need to merge reports:

OpenapiContracts::Coverage.merge_reports(
  $your_api_doc,
  *Dir[Rails.root.join("openapi_coverage_*.json")]
).generate(Rails.root.join("openapi_coverage.json"))

How it works

It uses the request.path, request.method, status and headers on the test subject (which must be the response) to find the request and response schemas in the OpenAPI document. Then it does the following checks:

• The response is documented
• Required headers are present
• Documented headers match the schema (via json_schemer)
• The response body matches the schema (via json_schemer)
• The request body matches the schema (via json_schemer) - if request_body: true

Known Issues

None at the moment :)

Future plans

• Validate Webmock stubs against the OpenAPI doc
• Generate example payloads from the OpenAPI doc