openapi_rspec 0.3 → 0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0367f850252eff7b267d205f702bb3424a10f88d3333b700f416fc337879ede2
-  data.tar.gz: ba6f7e1e9f0a8a706c6d5f712d50e2c5f916e56201a1131cd73505c6ceec4ce1
+  metadata.gz: 6bea441305836e75d93b65e38d4cb5297c16501228e286d6f444d2870a2bfc30
+  data.tar.gz: 3fa60f7de6682ba67b56b17562ad5e35d0548a51e8e61a5afe3f5462a38cbd36
 SHA512:
-  metadata.gz: 3104ab50af0749801e8a31b422f67c905f76cf75059aa5ba1121008a30990cdce08f941808914cb730b64f7a363bf5a4a839ad682b90a26352b3264b801bc445
-  data.tar.gz: eb0a1de49ad9adea06094c06b34d250b4f95f359dedc4c78ccf1e18d98cc5c0a93ec2e6afc1ab1a5fb54bda68827a679f49a24aa46c3680c9b44dc2103fa4913
+  metadata.gz: 6df382e223c149c2c250b8bb97a19470be4d784fe8bdd0cebc1161b806f69aef13cc13f6ca299a9c8f3df9792d2606bb64ecb893183d669769fb4b95aed27a6f
+  data.tar.gz: e4cf9b350d38b189fdf73e451143ccd5388e19104f9b557f62636e41791cfc2d28aec5e3e813f0868dc95eaa84165b3471585f3fa74b5f445e0e1743ac7f59a0

data/README.md

@@ -30,13 +30,225 @@ 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** use `params` helper method:
+
+```ruby
+# ...
+  post "/pets" do
+    params { { 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,40 +1,27 @@
-require "dry-configurable"
-require "openapi_validator"
-require "openapi_builder"
-require "rspec"
+# frozen_string_literal: true
 
-require "openapi_rspec/helpers"
-require "openapi_rspec/matchers"
-require "openapi_rspec/module_helpers"
-require "openapi_rspec/version"
+require 'dry-configurable'
+require 'openapi_validator'
+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
   extend Dry::Configurable
 
   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(openapi_path, **params)
-    session = Rack::Test::Session.new(config.app)
-    begin
-      response = session.get(openapi_path)
-    rescue StandardError => e
-      raise "Unable to perform GET request for swagger json: #{openapi_path} - #{e}."
-    end
-
-    parsed_doc = case openapi_path.split(".").last
-                 when "yml", "yaml"
-                   YAML.load(response.body)
-                 when "json"
-                   JSON.parse(response.body)
-                 else
-                   raise "Unable to parse OpenAPI doc, '#{openapi_path}' is undefined format"
-                 end
-    OpenapiValidator.call(parsed_doc, **params)
+  def self.api_by_path(path, **params)
+    doc = SchemaLoader.call(path)
+    api(doc, **params)
   end
 
   RSpec.configure do |config|

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,15 +1,18 @@
+# frozen_string_literal: true
+
 module OpenapiRspec
   module Helpers
     def request_params(metadata)
-      {}.tap do |hash|
-        hash[:method] = defined?(http_method) ? http_method : metadata[:method]
-        hash[:path] = defined?(uri) ? uri : metadata[:uri]
-        hash[:media_type] = openapi_rspec_media_type if defined? openapi_rspec_media_type
-        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
-      end
+      path = defined?(uri) ? uri : metadata[:uri]
+      method = defined?(http_method) ? http_method : metadata[:method]
+      {
+        method: method,
+        path: path,
+        params: path_params(path).merge!(openapi_rspec_params),
+        headers: openapi_rspec_headers,
+        query: openapi_rspec_query,
+        media_type: openapi_rspec_media_type
+      }
     end
 
     def path_params(path)

data/lib/openapi_rspec/matchers.rb

@@ -1,5 +1,7 @@
-require "openapi_rspec/documentation_validator"
-require "openapi_rspec/request_validator"
+# frozen_string_literal: true
+
+require 'openapi_rspec/documentation_validator'
+require 'openapi_rspec/request_validator'
 
 module OpenapiRspec
   module Matchers

data/lib/openapi_rspec/module_helpers.rb

@@ -1,8 +1,11 @@
+# frozen_string_literal: true
+
 module OpenapiRspec
   module ModuleHelpers
     def validate_code(code, &block)
       specify do |example|
-        validator = RequestValidator.new(**request_params(example.metadata[:openapi_rspec]), code: code)
+        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
@@ -49,10 +52,11 @@ module OpenapiRspec
     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,40 +1,51 @@
-require "rack/test"
-require "uri"
+# 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:, media_type: "application/json", params: {}, query: {}, headers: {})
-      @path = path
-      @method = method
-      @code = code
-      @media_type = media_type
-      @query = query
-      @headers = headers
-      @params = params
-    end
-
-    attr_reader :method, :path, :code, :media_type, :query, :headers, :params, :response
-
     def matches?(doc)
       @result = doc.validate_request(path: path, method: method, code: code, media_type: media_type)
+      return false unless result.valid?
 
-      return false unless @result.valid?
+      perform_request(doc)
+      result.validate_response(body: response.body, code: response.status)
+      result.valid?
+    end
 
-      headers.each do |key, value|
-        header key, value
+    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
-      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
@@ -48,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,
+        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 StandardError => 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 StandardError => 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.3"
+  VERSION = '0.4'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: openapi_rspec
 version: !ruby/object:Gem::Version
-  version: '0.3'
+  version: '0.4'
 platform: ruby
 authors:
 - Svyatoslav Kryukov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-09-14 00:00:00.000000000 Z
+date: 2019-10-07 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
@@ -123,6 +123,7 @@ 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: