openapi_rspec 0.2.0 → 0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0bc7e1b91f162a32c1d4be8d87814ebd2f62175f4d8846ac570179ee46c2d389
-  data.tar.gz: 11b302ed09c95e037be7732f0b388b912f076224ac24fb81047e9da70b53c901
+  metadata.gz: 748ba53aceac0ac02c274be192c1fadb895df66212e38da8bf9f88f80943f504
+  data.tar.gz: d2ab4b53ae116da4daf0bdaec48e2c8ff4d54b8ff98e1e4dc05bfd2d0d4c6dfc
 SHA512:
-  metadata.gz: 3d6edc80d5593740000f0ac64315c9eeab1dd514dc8a49fbedb216f89d10cac8a088fbfefc33ea10c180e8bc74f0238a0c8b9668ebd6a89434e799636c40eea9
-  data.tar.gz: 020771cf2c6aacdd5aa85f7cbfe8fbd499f46bcfb0096ba29c0f4e9eb03079a8e1d588172cb7df5d9aad3c10034e1fc69eab71c5de87afc4837e41ec0c0a508e
+  metadata.gz: 1a89fcf6b169fddf3ade6b8032354460046e5be264b38ba4b6fd164a2c5caaa1fc10a5369599701aa9b03bd347a6dbff313a3b7ca36e48e12ac2557fde4ca6e4
+  data.tar.gz: 15d575f392ac9ba39e2e5e11aa1732596f8ca9eaf43cbba72cf76ef036901d5bdd06ed40f8e5c7f5ff45afcd1038b2552c266e1bd420b0703642322c08ce2bde

data/README.md

@@ -7,6 +7,7 @@
 [![Build Status](https://travis-ci.org/medsolutions/openapi_rspec.svg?branch=master)][travis]
 [![Code Climate](https://codeclimate.com/github/medsolutions/openapi_rspec/badges/gpa.svg)][codeclimate]
 [![Test Coverage](https://codeclimate.com/github/medsolutions/openapi_rspec/badges/coverage.svg)][codeclimate]
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
 
 Test your API against OpenApi v3 documentation
 
@@ -30,13 +31,238 @@ Or install it yourself as:
 
 ## Usage
 
-See spec/example_spec.rb
+Add `spec/openapi_helper.rb` and set `OpenapiRspec.config.app`:
 
-## Development
+```ruby
+# spec/openapi_helper.rb
+
+require "rails_helper"
+
+OpenapiRspec.config.app = Rails.application # or any other Rack app, thanks to rack-test gem
+```
+
+Then configure path to your documentation. You can use documentation defined as:
+- static file with `.yaml`/`.yml` or `.json` extension
+- uri to OpenAPI schema in your application
+
+```ruby
+# spec/openapi_helper.rb
+
+#...
+
+# static file
+API_V1 = OpenapiRspec.api("./spec/data/openapi.yml")
+
+# application path
+API_V2 = OpenapiRspec.api_by_path("/openapi.json")
+```
+
+
+### Validate documentation against the OpenAPI 3.0 Specification:
+
+```ruby
+RSpec.describe "API v1" do
+  subject { API_V1 }
+
+  it "is valid OpenAPI spec" do
+    expect(subject).to validate_documentation
+  end
+end
+```
+
+#### Validate documentation against custom schema
+
+You can validate documentation against additional custom schemata, for example, to enforce organization documentation standards:
+
+```ruby
+# spec/openapi_helper.rb
+
+#...
+
+API_V1 = OpenapiRspec.api("./spec/data/openapi.yml", additional_schemas: ["./spec/data/acme_schema.yml"])
+```
+
+```ruby
+# openapi_v1_spec.rb
+
+RSpec.describe "API v1" do
+  subject { API_V1 }
+
+  it "is valid OpenAPI and ACME spec" do
+    expect(subject).to validate_documentation
+  end
+end
+```
+
+### Validate endpoints
+
+General example:
+
+```ruby
+require "openapi_rspec"
+
+RSpec.describe "API v1 /pets" do
+
+  subject { API_V1 }
+
+  get "/pets" do
+    headers { { "X-Client-Device" => "ios" } }
+    query { { tags: ["lucky"] } }
+
+    validate_code(200) do |validator|
+      result = JSON.parse(validator.response.body)
+      expect(result.first["name"]).to eq("Lucky")
+    end
+  end
+
+  post "/pets" do
+    params { { name: "Lucky" } }
+
+    validate_code(201)
+  end
+
+  get "/pets/{id}" do
+    let(:id) { 23 }
+
+    validate_code(200)
+
+    context "when pet not found" do
+      let(:id) { "bad_id" }
+
+      validate_code(404)
+    end
+  end
+```
+
+#### Helper methods
+
+To validate response use:
+- `get`, `post`, `put`, `patch`, `delete` and `head` methods to describe operation with the path
+- `validate_code` method with passed expected code
+
+```ruby
+# ...
+  get "/pets" do
+    validate_code(200)
+  end
+# ...
+```
+
+To set **request body** (as form data) use `params` helper method and provide a `Hash`:
+
+```ruby
+# ...
+  post "/pets" do
+    params { { name: "Lucky" } }
+
+    validate_code(201)
+  end
+# ...
+```
+
+To set **raw request body** use the `params` helper method and provide a `String`:
+
+```ruby
+# ...
+  post "/pets" do
+    params { JSON.dump(name: "Lucky") }
+
+    validate_code(201)
+  end
+# ...
+```
+
+
+To set **path parameter** use `let` helper method:
+
+```ruby
+# ...
+  get "/pets/{id}" do
+    let(:id) { 23 }
+
+    validate_code(200)
+  end
+# ...
+```
+
+To set **query parameters** use `query` helper method:
+
+```ruby
+# ...
+  get "/pets" do
+    query { { name: "lucky" } }
+
+    validate_code(200)
+  end
+# ...
+```
+
+To set **header parameters** use `headers` helper method:
+
+```ruby
+# ...
+  get "/pets" do
+    headers { { "X-User-Token" => "bad_token" } }
+
+    validate_code(401)
+  end
+# ...
+```
+
+#### Custom response validation
+
+You can access response to add custom validation like this:
+
+```ruby
+# ...
+  get "/pets" do
+    validate_code(200) do |validator|
+      result = JSON.parse(validator.response.body)
+      expect(result).not_to be_empty
+    end
+  end
+# ...
+```
+
+#### Prefix API requests
+
+To prefix each request with `"/some_path"` use `:api_base_path` option:
+
+```ruby
+# spec/openapi_helper.rb
+
+#...
+
+API_V1 = OpenapiRspec.api("./spec/data/openapi.yml", api_base_path: "/some_path")
+```
+
+#### Validate that all documented routes are tested
+
+To validate this we will use a small hack:
+
+```ruby
+# spec/openapi_helper.rb
+
+# ...
+
+API_V1_DOC = OpenapiRspec.api("./openapi/openapi.yml", api_base_path: "/api/v1")
+
+RSpec.configure do |config|
+  config.after(:suite) do
+    unvalidated_requests = API_V1_DOC.unvalidated_requests
+
+    if unvalidated_requests.any? && ENV["TEST_COVERAGE"]
+      raise unvalidated_requests.map { |path| "Path #{path.join(' ')} not tested" }.join("\n")
+    end
+  end
+end
+```
+
+Then run your specs:
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+    $ TEST_COVERAGE=1 rspec
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+This will raise an error if any of the documented paths are not validated.
 
 ## Contributing
 

data/lib/openapi_rspec.rb

@@ -1,11 +1,13 @@
+# frozen_string_literal: true
+
 require "dry-configurable"
 require "openapi_validator"
-require "openapi_builder"
 require "rspec"
 
 require "openapi_rspec/helpers"
 require "openapi_rspec/matchers"
 require "openapi_rspec/module_helpers"
+require "openapi_rspec/schema_loader"
 require "openapi_rspec/version"
 
 module OpenapiRspec
@@ -13,11 +15,15 @@ module OpenapiRspec
 
   setting :app, reader: true
 
-  def self.api(doc, build: false, **params)
-    doc = OpenapiBuilder.call(doc).data if build
+  def self.api(doc, **params)
     OpenapiValidator.call(doc, **params)
   end
 
+  def self.api_by_path(path, **params)
+    doc = SchemaLoader.call(path)
+    api(doc, **params)
+  end
+
   RSpec.configure do |config|
     config.extend ModuleHelpers
     config.include Helpers

data/lib/openapi_rspec/documentation_validator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module OpenapiRspec
   class DocumentationValidator
     def matches?(doc)
@@ -6,7 +8,7 @@ module OpenapiRspec
     end
 
     def description
-      "be a valid documentation"
+      "be a valid OpenAPI documentation"
     end
 
     def failure_message

data/lib/openapi_rspec/helpers.rb

@@ -1,20 +1,26 @@
+# frozen_string_literal: true
+
 module OpenapiRspec
   module Helpers
-    def expect_validate_request(code, metadata: {})
-      expect(subject).to validate_request(**request_params(metadata), code: code)
-    end
-    
     def request_params(metadata)
-      Hash.new.tap do |hash|
-        hash[:method] = defined?(http_method) ? http_method : metadata[:method]
-        hash[:path] = defined?(uri) ? uri : metadata[:uri]
-        hash[:params] = path_params(hash[:path])
-        hash[:params].merge!(openapi_rspec_params) if defined? openapi_rspec_params
-        hash[:headers] = openapi_rspec_headers if defined? openapi_rspec_headers
-        hash[:query] = openapi_rspec_query if defined? openapi_rspec_query
+      path = defined?(uri) ? uri : metadata[:uri]
+      method = defined?(http_method) ? http_method : metadata[:method]
+      params = if openapi_rspec_params.is_a?(Hash)
+        path_params(path).merge!(openapi_rspec_params)
+      else
+        openapi_rspec_params
       end
+
+      {
+        method: method,
+        path: path,
+        params: params,
+        headers: openapi_rspec_headers,
+        query: openapi_rspec_query,
+        media_type: openapi_rspec_media_type,
+      }
     end
-    
+
     def path_params(path)
       path_params = {}
       path.scan(/\{([^\}]*)\}/).each do |param|

data/lib/openapi_rspec/matchers.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "openapi_rspec/documentation_validator"
 require "openapi_rspec/request_validator"
 

data/lib/openapi_rspec/module_helpers.rb

@@ -1,53 +1,62 @@
+# frozen_string_literal: true
+
 module OpenapiRspec
   module ModuleHelpers
     def validate_code(code, &block)
       specify do |example|
-        expect_validate_request(code, metadata: example.metadata[:openapi_rspec])
-        instance_eval &block if block_given?
+        metadata = example.metadata[:openapi_rspec]
+        validator = RequestValidator.new(**request_params(metadata), code: code)
+        expect(subject).to validator
+        instance_exec validator, &block if block_given?
       end
     end
 
     def params(&block)
       let(:openapi_rspec_params, &block)
     end
-    
+
+    def media_type(&block)
+      let(:openapi_rspec_media_type, &block)
+    end
+
     def headers(&block)
       let(:openapi_rspec_headers, &block)
     end
-    
+
     def query(&block)
       let(:openapi_rspec_query, &block)
     end
-    
+
     def get(*args, &block)
       process(:get, *args, &block)
     end
-    
+
     def post(*args, &block)
       process(:post, *args, &block)
     end
-    
+
     def put(*args, &block)
       process(:put, *args, &block)
     end
-    
+
     def delete(*args, &block)
       process(:delete, *args, &block)
     end
-    
+
     def head(*args, &block)
       process(:head, *args, &block)
     end
-    
+
     def patch(*args, &block)
       process(:patch, *args, &block)
     end
-    
+
     def process(method, uri)
-      metadata[:openapi_rspec] = {
-        uri: uri,
-        method: method
-      }
+      metadata[:openapi_rspec] = {uri: uri, method: method}
+      let(:openapi_rspec_media_type) { "application/json" }
+      let(:openapi_rspec_params) { {} }
+      let(:openapi_rspec_headers) { {} }
+      let(:openapi_rspec_query) { {} }
       context "#{method.to_s.upcase} #{uri}" do
         yield if block_given?
       end

data/lib/openapi_rspec/request_validator.rb

@@ -1,38 +1,51 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
 require "rack/test"
 require "uri"
 
 module OpenapiRspec
   class RequestValidator
+    extend Dry::Initializer
     include Rack::Test::Methods
 
+    option :path
+    option :method
+    option :code
+    option :media_type
+    option :params
+    option :query
+    option :headers
+
+    attr_reader :response, :result
+
     def app
       OpenapiRspec.app
     end
 
-    def initialize(path:, method:, code:, params: {}, query: {}, headers: {})
-      @path = path
-      @method = method
-      @code = code
-      @query = query
-      @headers = headers
-      @params = params
-    end
+    def matches?(doc)
+      @result = doc.validate_request(path: path, method: method, code: code, media_type: media_type)
+      return false unless result.valid?
 
-    attr_reader :method, :path, :code, :query, :headers, :params
+      perform_request(doc)
+      result.validate_response(body: response.body, code: response.status)
+      result.valid?
+    end
 
-    def matches?(doc)
-      @result = doc.validate_request(path: path, method: method, code: code)
-      return false unless @result.valid?
+    def description
+      "return valid response with code #{code} on `#{method.to_s.upcase} #{path}`"
+    end
 
-      headers.each do |key, value|
-        header key, value
+    def failure_message
+      if response
+        (%W[Response: #{response.body}] + result.errors).join("\n")
+      else
+        result.errors.join("\n")
       end
-      request(request_uri(doc), method: method, **request_params)
-      @response = last_response
-      @result.validate_response(body: @response.body, code: @response.status)
-      @result.valid?
     end
 
+    private
+
     def request_uri(doc)
       path.scan(/\{([^\}]*)\}/).each do |param|
         key = param.first.to_sym
@@ -46,23 +59,19 @@ module OpenapiRspec
       "#{doc.api_base_path}#{path}?#{URI.encode_www_form(query)}"
     end
 
+    def perform_request(doc)
+      headers.each do |key, value|
+        header key, value
+      end
+      request(request_uri(doc), method: method, **request_params)
+      @response = last_response
+    end
+
     def request_params
       {
         headers: headers,
         params: params,
       }
     end
-
-    def description
-      "return valid response with code #{code} on `#{method.to_s.upcase} #{path}`"
-    end
-
-    def failure_message
-      if @response
-        (%W(Response: #{@response.body}) + @result.errors).join("\n")
-      else
-        @result.errors.join("\n")
-      end
-    end
   end
 end

data/lib/openapi_rspec/schema_loader.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module OpenapiRspec
+  module SchemaLoader
+    def self.call(path, app: OpenapiRspec.config.app)
+      response = request(path, app)
+      parse(response)
+    end
+
+    def self.parse(schema)
+      begin
+        JSON.parse(schema)
+      rescue JSON::ParserError
+        YAML.safe_load(schema)
+      end
+    rescue => e
+      raise "Unable to parse OpenAPI schema. #{e}"
+    end
+
+    def self.request(path, app)
+      session = Rack::Test::Session.new(app)
+      response = session.get(path)
+
+      raise "Response code: #{response.status}" unless response.successful?
+      raise "Empty body" if response.body.empty?
+
+      response.body
+    rescue => e
+      raise "Unable to perform GET request for the OpenAPI schema '#{path}'. #{e}"
+    end
+  end
+end

data/lib/openapi_rspec/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module OpenapiRspec
-  VERSION = "0.2.0"
+  VERSION = "0.5"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: openapi_rspec
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: '0.5'
 platform: ruby
 authors:
 - Svyatoslav Kryukov
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2019-04-27 00:00:00.000000000 Z
+date: 2020-08-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-configurable
@@ -25,19 +25,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.8'
 - !ruby/object:Gem::Dependency
-  name: openapi_builder
+  name: dry-initializer
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: openapi_validator
   requirement: !ruby/object:Gem::Requirement
@@ -98,17 +98,17 @@ dependencies:
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: 12.3.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
-description: 
+        version: 12.3.3
+description:
 email:
 - s.g.kryukov@yandex.ru
 executables: []
@@ -123,12 +123,13 @@ files:
 - lib/openapi_rspec/matchers.rb
 - lib/openapi_rspec/module_helpers.rb
 - lib/openapi_rspec/request_validator.rb
+- lib/openapi_rspec/schema_loader.rb
 - lib/openapi_rspec/version.rb
 homepage: https://github.com/medsolutions/openapi_rspec
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -144,7 +145,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.0.3
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Test your API against OpenApi v3 documentation
 test_files: []