Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mkon/openapi_contracts

Openapi schemas as API contracts
https://github.com/mkon/openapi_contracts

json-schema openapi redoc rspec ruby swagger

Last synced: 2 months ago
JSON representation

Openapi schemas as API contracts

Awesome Lists containing this project

README 

        
# OpenapiContracts



[![Push & PR](https://github.com/mkon/openapi_contracts/actions/workflows/main.yml/badge.svg)](https://github.com/mkon/openapi_contracts/actions/workflows/main.yml)

[![Gem Version](https://badge.fury.io/rb/openapi_contracts.svg)](https://badge.fury.io/rb/openapi_contracts)

[![Depfu](https://badges.depfu.com/badges/8ac57411497df02584bbf59685634e45/overview.svg)](https://depfu.com/github/mkon/openapi_contracts?project_id=35354)



Use OpenAPI documentation as an API contract.



Currently supports OpenAPI documentation in the structure as used by [Redocly](https://github.com/Redocly/create-openapi-repo), 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:



```ruby

# This must point to the folder where the OAS file is stored

$doc = OpenapiContracts::Doc.parse(Rails.root.join('spec/fixtures/openapi/api-docs'), '')

```



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:



```ruby

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:



```ruby

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.



```ruby

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.



```ruby

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



```ruby

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:



```ruby

# 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:



```ruby

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:



```ruby

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