openapi_contracts 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 827fa48e143922260919e9a3231316f1505e34444a7b6a15051ccdb0303c1440
+  data.tar.gz: c02b963ccc67dd5c71c50843a4a517a4c90a9913b182f18c588a1b044a34992b
+SHA512:
+  metadata.gz: cbd07c48ee48324e0cdae9c7ea8e69defe61cdfc9c17eb4aaea396debef6d5109bbaae153cda430924d533ea415c7fc02b4a2e8c440c3ad121ca64b53aa49988
+  data.tar.gz: a5c26d7a6391f38443688a7a7d43ba785af7ed0840e651e6a60bb0dcbbc83e09e9ec0fa860a9a9f18c2b407c11b866b9e46eaad2de51b933c60a0980e78a5f37

data/README.md

@@ -0,0 +1,55 @@
+# OpenapiContracts
+
+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 responses match the OpenAPI documentation.
+
+## Usage
+
+First parse your api documentation:
+
+```ruby
+# This must point to the folder where the "openapi.yaml" file is
+$doc = OpenapiContracts::Doc.parse(Rails.root.join('spec', 'fixtures', 'openapi', 'api-docs', 'openapi'))
+```
+
+Ideally you do this once in a 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($api_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($api_doc)
+}
+```
+
+### 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 response schema 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-schema)
+* The response body matches the schema (via json-schema)
+
+## Future plans
+
+* Validate sent requests against the request schema
+* Validate Webmock stubs against the OpenAPI doc
+* Generate example payloads from the OpenAPI doc

data/lib/openapi_contracts/doc/header.rb

@@ -0,0 +1,18 @@
+module OpenapiContracts
+  class Doc::Header
+    attr_reader :name
+
+    def initialize(name, data)
+      @name = name
+      @data = data
+    end
+
+    def required?
+      @data['required']
+    end
+
+    def schema
+      @data['schema']
+    end
+  end
+end

data/lib/openapi_contracts/doc/parser.rb

@@ -0,0 +1,32 @@
+module OpenapiContracts
+  class Doc::Parser
+    def self.call(dir)
+      new(dir).parse('openapi.yaml')
+    end
+
+    def initialize(dir)
+      @dir = dir
+    end
+
+    def parse(path = 'openapi.yaml')
+      abs_path = @dir.join(path)
+      yaml = File.read(abs_path)
+      data = YAML.safe_load(yaml)
+      join_components(abs_path.dirname, data)
+    end
+
+    private
+
+    def join_components(current_path, data)
+      data.each_with_object({}) do |(key, val), m|
+        if val.is_a?(Hash)
+          m[key] = join_components(current_path, val)
+        elsif key == '$ref'
+          m.merge! parse(current_path.join(val))
+        else
+          m[key] = val
+        end
+      end
+    end
+  end
+end

data/lib/openapi_contracts/doc/response.rb

@@ -0,0 +1,27 @@
+module OpenapiContracts
+  class Doc::Response
+    def initialize(data)
+      @data = data
+    end
+
+    def headers
+      return @headers if instance_variable_defined? :@headers
+
+      @headers = @data.fetch('headers', {}).map do |(k, v)|
+        Doc::Header.new(k, v)
+      end
+    end
+
+    def schema_for(content_type)
+      @data.dig('content', content_type, 'schema')
+    end
+
+    def no_content?
+      !@data.key? 'content'
+    end
+
+    def supports_content_type?(content_type)
+      @data.dig('content', content_type).present?
+    end
+  end
+end

data/lib/openapi_contracts/doc.rb

@@ -0,0 +1,21 @@
+module OpenapiContracts
+  class Doc
+    autoload :Header,   'openapi_contracts/doc/header'
+    autoload :Parser,   'openapi_contracts/doc/parser'
+    autoload :Response, 'openapi_contracts/doc/response'
+
+    def self.parse(dir)
+      new Parser.call(dir)
+    end
+
+    def initialize(spec, pointer = [])
+      @spec = spec
+    end
+
+    delegate :dig, :fetch, :[], to: :@spec
+
+    def response_for(path, method, status)
+      dig('paths', path, method, 'responses', status)&.then { |d| Response.new(d) }
+    end
+  end
+end

data/lib/openapi_contracts/matchers/match_openapi_doc.rb

@@ -0,0 +1,98 @@
+module OpenapiContracts
+  module Matchers
+    class MatchOpenapiDoc
+      def initialize(doc)
+        @doc = doc
+        @errors = []
+      end
+
+      def with_http_status(status)
+        if status.is_a? Symbol
+          @status = Rack::Utils::SYMBOL_TO_STATUS_CODE[status]
+        else
+          @status = status
+        end
+        self
+      end
+
+      def matches?(response)
+        @response = response
+        response_documented? && http_status_matches? && [headers_match?, body_matches?].all?
+        @errors.empty?
+      end
+
+      def description
+        desc = 'to match the openapi schema'
+        desc << " with #{http_status_desc(@status)}" if @status
+        desc
+      end
+
+      def failure_message
+        @errors.map { |e| "* #{e}" }.join("\n")
+      end
+
+      def failure_message_when_negated
+        'request matched the schema'
+      end
+
+      private
+
+      def response_desc
+        "#{@response.request.request_method} #{@response.request.path}"
+      end
+
+      def response_spec
+        @response_spec ||= @doc.response_for(@response.request.path, @response.request.request_method.downcase, @response.status.to_s)
+      end
+
+      def response_content_type
+        @response.headers['Content-Type'].split(';').first
+      end
+
+      def headers_match?
+        response_spec.headers.each do |header|
+          value = @response.headers[header.name]
+          if value.blank?
+            @errors << "Missing header #{header.name}" if header.required?
+          elsif (errors = JSON::Validator.fully_validate(header.schema, value)).any?
+            @errors << "Header #{header.name} does not match: #{errors.to_sentence}"
+          end
+        end
+        @errors.empty?
+      end
+
+      def http_status_desc(status = nil)
+        status ||= @response.status
+        "http status #{Rack::Utils::HTTP_STATUS_CODES[status]} (#{status})"
+      end
+
+      def http_status_matches?
+        if @status.present? && @status != @response.status
+          @errors << "Response has #{http_status_desc}"
+          false
+        else
+          true
+        end
+      end
+
+      def body_matches?
+        if response_spec.no_content?
+          @errors << "Expected empty response body" if @response.body.present?
+        elsif !response_spec.supports_content_type?(response_content_type)
+          @errors << "Undocumented response with content-type #{response_content_type.inspect}"
+        else
+          @schema = response_spec.schema_for(response_content_type)
+          @errors += JSON::Validator.fully_validate(@schema, JSON(@response.body))
+        end
+        @errors.empty?
+      end
+
+      def response_documented?
+        return true if response_spec
+
+        @errors << "Undocumented request/response for #{response_desc.inspect} with #{http_status_desc}"
+        false
+      end
+    end
+  end
+end

data/lib/openapi_contracts/matchers.rb

@@ -0,0 +1,13 @@
+module OpenapiContracts
+  module Matchers
+    autoload :MatchOpenapiDoc, 'openapi_contracts/matchers/match_openapi_doc'
+
+    def match_openapi_doc(doc)
+      MatchOpenapiDoc.new(doc)
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.include OpenapiContracts::Matchers
+end

data/lib/openapi_contracts.rb

@@ -0,0 +1,17 @@
+require 'active_support'
+if ActiveSupport.version >= Gem::Version.new('7')
+  require 'active_support/isolated_execution_state' # required by array somehow
+end
+require 'active_support/core_ext/array'
+require 'active_support/core_ext/module'
+
+require 'json-schema'
+
+module OpenapiContracts
+  autoload :Doc,      'openapi_contracts/doc'
+  autoload :Matchers, 'openapi_contracts/matchers'
+end
+
+RSpec.configure do |config|
+  config.include OpenapiContracts::Matchers
+end

metadata

@@ -0,0 +1,130 @@
+--- !ruby/object:Gem::Specification
+name: openapi_contracts
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- mkon
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-05-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
+- !ruby/object:Gem::Dependency
+  name: json-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.8.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.8.1
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.2.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.2.3
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.11.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.11.0
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.2
+description:
+email:
+- konstantin@munteanu.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/openapi_contracts.rb
+- lib/openapi_contracts/doc.rb
+- lib/openapi_contracts/doc/header.rb
+- lib/openapi_contracts/doc/parser.rb
+- lib/openapi_contracts/doc/response.rb
+- lib/openapi_contracts/matchers.rb
+- lib/openapi_contracts/matchers/match_openapi_doc.rb
+homepage: https://github.com/mkon/openapi_contracts
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key:
+specification_version: 4
+summary: Openapi schemas as API contracts
+test_files: []