Need help with apivore?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

westfieldlabs
198 Stars 58 Forks Apache License 2.0 326 Commits 23 Opened issues

Description

Tests your rails API against its Swagger description of end-points, models, and query parameters.

Services available

!
?

Need anything else?

Contributors list

Build Status

Code Climate

Apivore

Automatically tests your rails API against its OpenAPI (Swagger) description of end-points, models, and query parameters.

Currently supports and validates against OpenAPI 2.0, (see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)

Installation

To use Apivore, add the following to your Gemfile:

gem 'apivore'

WARNING: If apivore is listed in the Gemfile above rspec then some issues, specifically

NameError: uninitialized constant RSpec::Mocks
, may arise when trying to run specs.

Usage

Create a new request spec in spec/requests: ```ruby require 'spec_helper'

RSpec.describe 'the API', type: :apivore, order: :defined do subject { Apivore::SwaggerChecker.instance_for('/swagger.json') }

context 'has valid paths' do # tests go here end

context 'and' do it 'tests all documented routes' do expect(subject).to validateallpaths end end end ``

using the path to your application's Swagger 2.0 documentation. The convention is
/swagger.json`.

This will validate the json against the Swagger 2.0 schema and allow you to add tests for each documented endpoint combination of a path, method, and expected response.

If your Swagger documentation contains a schema for the response model, the generated tests will test whether the response conforms to that model.

For paths that take parameters, listed in the Swagger docs like

/deals/{id}.json
, values need to be passed to Apivore to substitute in to access the responses generated by your test data.

This is accomplished by passing the params into the validates function. ```ruby context 'has valid paths' do let(:params) { { "id" => 1 } } specify do expect(subject).to validate( :get, '/deals/{id}.json', 200, params ) end

# or alternatively

it { isexpected.to validate( :get, '/deals/{id}.json', 200, params ) } end ``

A query string can be specified with the
query_string` key as follows:

expect(subject).to validate(
  :get '/deals', 200, {"_query_string" => "title=Hello%20World&edition=3"}
)

Parameters in the query string are not validated or processed by Apivore in any way.

Post parameters can be specified with the

_data
key as follows:
expect(subject).to validate(
  :post '/deals', 200, {"_data" => {'title' => 'Hello World'} }
)

HTTP headers can be specified via the

_headers
key:
expect(subject).to validate(
  :get '/deals', 200, {"_headers" => {'accept' => 'application/json'} }
)

Your Swagger.json can be validated against additional custom schemata, for example to enforce organisation API documentation standards, by using the following syntax:

it 'additionally conforms to a custom schema' do
  expect(subject).to conform_to(".json")
end

We have included an example here. The file path to this custom schema is stored in

Apivore::CustomSchemaValidator::WF_SCHEMA
, if you wish to use it.

Run the tests as part of your normal rspec test suite, e.g.,

rake spec:requests

Useful Resources

  • http://json-schema.org/
  • https://github.com/OAI/OpenAPI-Specification
  • https://github.com/ruby-json-schema/json-schema

License

Copyright 2014 Westfield Labs Corporation

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This project includes and makes use of the OpenAPI (Swagger) 2.0 schema json (Copyright 2016 The Linux Foundation. Released under the Apache License) included here as

data/swagger_2.0_schema.json

It also includes a copy of http://json-schema.org/draft-04/schema, included as

data/draft04_schema.json
. These schemata are included to prevent network resource fetching and speed up validation times considerably.

Contributors

  • Charles Horn (https://github.com/hornc)
  • Leon Dewey (https://github.com/leondewey)
  • Max Brosnahan (https://github.com/gingermusketeer)

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.