openapi_first 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55b0bba2e51dd0517e3306e34d345ec34d2165a2a3d8536c140941b74818d945
-  data.tar.gz: 8ba6d8d04a3abb38e60a2716f7515df945b870e0b8a874b6d217773894e4642c
+  metadata.gz: 6888d00f37a7dce1f2b22ad9da04f4ecb69236ea18221173fc77dac1b5edba6c
+  data.tar.gz: 8eca9351e46942b1acf6fa47d3394dbfa9a85c4f0dc3dc1f77c075d2818bc3ed
 SHA512:
-  metadata.gz: d072794a009783f7cb4ea4141ffadfaea699701954f1c994dc6db69faf18e36ed554bdeb979d81d5b31d7abb8a668e17113156e96ccf311b99a0187a7d48dc06
-  data.tar.gz: 608a19940d52d6e554c6d53a95ea1942731d2a8df9118a3c91202d7b8220c7eb0899bffccbcd9a3ff6213ad520851ab446909bd6e2b4d17950937017179f264b
+  metadata.gz: 967dd87e43808f328a5ab72e99cf04c4b37eb756b2a4ef06925e3e419b038583e014cf3c11074168f02fd07b16db4ba266f743a884a608f37e6c1bfeed0ce911
+  data.tar.gz: 9c2a62d290c09417c0c75eaec88427b847f43d787e3cb548dcef543749a98f7252d5915de48fe64c9eb34eca8f579590f1d94bec9455c1ba08932b1a5de5c7f4

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Unreleased
 
+# 0.6.1
+
+- Make ResponseValidator errors easier to read
+
 # 0.6.0
 
 - Set the content-type based on the OpenAPI description [#29](https://github.com/ahx/openapi-first/pull/29)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    openapi_first (0.6.0)
+    openapi_first (0.6.1)
       json_schemer (~> 0.2)
       multi_json (~> 1.13)
       oas_parser (~> 0.19)
@@ -29,7 +29,7 @@ GEM
     hansi (0.2.0)
     i18n (1.6.0)
       concurrent-ruby (~> 1.0)
-    jaro_winkler (1.5.2)
+    jaro_winkler (1.5.3)
     json_schemer (0.2.0)
       ecma-re-validator (~> 0.2.0)
       hana (~> 1.3.3)
@@ -69,23 +69,23 @@ GEM
       rspec-core (~> 3.8.0)
       rspec-expectations (~> 3.8.0)
       rspec-mocks (~> 3.8.0)
-    rspec-core (3.8.0)
+    rspec-core (3.8.2)
       rspec-support (~> 3.8.0)
-    rspec-expectations (3.8.3)
+    rspec-expectations (3.8.4)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.8.0)
-    rspec-mocks (3.8.0)
+    rspec-mocks (3.8.1)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.8.0)
-    rspec-support (3.8.0)
-    rubocop (0.69.0)
+    rspec-support (3.8.2)
+    rubocop (0.72.0)
       jaro_winkler (~> 1.5.1)
       parallel (~> 1.10)
       parser (>= 2.6)
       rainbow (>= 2.2.2, < 4.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 1.7)
-    ruby-progressbar (1.10.0)
+    ruby-progressbar (1.10.1)
     thread_safe (0.3.6)
     tzinfo (1.2.5)
       thread_safe (~> 0.1)

data/README.md

@@ -1,12 +1,12 @@
 # OpenapiFirst
 
-OpenapiFirst helps to implement Rack based HTTP APIs based on an [OpenApi](https://www.openapis.org/) API description. The idea is that you create an API description first, then add minimal code about your business logic (some call this "Resolver") and be done.
+OpenapiFirst helps to implement HTTP APIs based on an [OpenApi](https://www.openapis.org/) API description. The idea is that you create an API description first, then add minimal code about your business logic (some call this "Resolver") and be done.
 
 ## TL;DR
 
 ```ruby
 module Pets
-  def self.find_pet(params, _res) # "find_pet" is an operationId from your OpenApi file
+  def self.find_pet(params, res)
     {
       id: params['id'],
       name: 'Oscar'
@@ -22,10 +22,16 @@ run OpenapiFirst.app('./openapi/openapi.yaml', namespace: Pets)
 The above will:
 
 - Validate the request and respond with 400 if the request does not match against your spec
-- Map the request (for example `GET /pet/1`) to the method call `Pets.find_pet`
+- Map the request to a method call `Pets.find_pet` based on the `operationId` in the API description
 - Set the response content type according to your spec (here with the default status code `200`)
 
-### Usage as Rack middlware
+Resolver functions (`find_pet`) are called with two arguments:
+
+- `params` - Holds the parsed request body, filtered query params and path parameters
+- `res` - Holds a Rack::Response that you can modify if needed
+  If you want to access to plain Rack env you can call `params.env`.
+
+### Usage as Rack middleware
 
 ```ruby
 # Just like the above, except the last line
@@ -40,6 +46,7 @@ When using the middleware, all requests that are not part of the API description
 See [example](examples)
 
 ## Missing features
+
 See [issues](https://github.com/ahx/openapi_first/issues).
 
 ## Start
@@ -58,6 +65,67 @@ gem 'openapi_first'
 
 OpenapiFirst uses [`multi_json`](https://rubygems.org/gems/multi_json).
 
+## Testing
+
+OpenapiFirst offers tools to help testing your app against your API description.
+
+### Response validation
+
+Response validation is to make sure your app responds as described in your API description. You usually do this in your tests using [rack-test](https://github.com/rack-test/rack-test).
+
+```ruby
+# In your test:
+require 'openapi_first/response_validator'
+spec = OpenapiFirst.load('petstore.yaml')
+validator = OpenapiFirst::ResponseValidator.new(spec)
+validator.validate(last_request, last_response).errors? # => true or false
+```
+
+TODO: Add RSpec matcher (via extra rubygem)
+
+### Coverage
+
+(This is a bit experimental. Please try it out and give feedback.)
+
+`OpenapiFirst::Coverage` helps you make sure, that you have called all endpoints of your OAS file when running tests via `rack-test`.
+
+```ruby
+# In your test (rspec example):
+require 'openapi_first/coverage'
+
+describe MyApp do
+  include Rack::Test::Methods
+
+  before(:all) do
+    spec = OpenapiFirst.load('petstore.yaml')
+    @app_wrapper = OpenapiFirst::Coverage.new(MyApp, spec)
+  end
+
+  after(:all) do
+    message = "The following paths have not been called yet: #{@app_wrapper.to_be_called}"
+    expect(@app_wrapper.to_be_called).to be_empty
+  end
+
+  # Overwrite `#app` to make rack-test call the wrapped app
+  def app
+    @app_wrapper
+  end
+
+  it 'does things' do
+    get '/i/my/stuff'
+    # …
+  end
+end
+```
+
+## Mocking
+
+Mocking is currently out of scope. Try https://github.com/JustinFeng/fakeit or something else.
+
+## Alternatives
+
+This gem is inspired by [committee](https://github.com/interagent/committee), which has much more features like response stubs or support for Hyper-Schema or OpenAPI 2.
+
 ## How it works
 
 OpenapiFirst offers Rack middlewares to auto-implement different aspects of request validation:
@@ -73,7 +141,7 @@ spec = OpenapiFirst.load('petstore.yaml')
 use OpenapiFirst::Router, spec: spec
 ```
 
-If the request is not valid, these middlewares return a 400 status code with a body that describes the error. If unkwon routes in your application exist, which are not specified in the openapi spec file, set `:allow_unknown_operation` to `true`.
+If the request is not valid, these middlewares return a 400 status code with a body that describes the error. If unkwon routes in your application exist, which are not specified in the API description, set `:allow_unknown_operation` to `true`.
 
 The error responses conform with [JSON:API](https://jsonapi.org).
 
@@ -184,7 +252,8 @@ Response validation is to make sure your app responds as described in your OpenA
 require 'openapi_first/response_validator'
 spec = OpenapiFirst.load('petstore.yaml')
 validator = OpenapiFirst::ResponseValidator.new(spec)
-validator.validate(last_request, last_response).errors? # => true or false
+
+expect(validator.validate(last_request, last_response).errors).to be_empty
 ```
 
 TODO: Add RSpec matcher (via extra rubygem)
@@ -226,7 +295,7 @@ end
 
 ## Mocking
 
-Currently out of scope. Use https://github.com/JustinFeng/fakeit or something else.
+Currently out of scope.
 
 ## Alternatives
 

data/lib/openapi_first.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'oas_parser'
+require 'openapi_first/definition'
 require 'openapi_first/version'
 require 'openapi_first/router'
 require 'openapi_first/query_parameter_validation'
@@ -15,7 +16,7 @@ module OpenapiFirst
   QUERY_PARAMS = 'openapi_first.query_params'
 
   def self.load(spec_path)
-    OasParser::Definition.resolve(spec_path)
+    Definition.new(OasParser::Definition.resolve(spec_path))
   end
 
   def self.app(spec, namespace:)

data/lib/openapi_first/coverage.rb

@@ -7,29 +7,21 @@ module OpenapiFirst
     def initialize(app, spec)
       @app = app
       @spec = spec
-      @to_be_called = spec.endpoints.map do |endpoint|
-        endpoint_id(endpoint)
+      @to_be_called = spec.operations.map do |operation|
+        endpoint_id(operation)
       end
     end
 
     def call(env)
-      endpoint = endpoint_for_request(Rack::Request.new(env))
-      @to_be_called.delete(endpoint_id(endpoint)) if endpoint
+      operation = @spec.find_operation(Rack::Request.new(env))
+      @to_be_called.delete(endpoint_id(operation)) if operation
       @app.call(env)
     end
 
     private
 
-    def endpoint_id(endpoint)
-      "#{endpoint.path.path}##{endpoint.method}"
-    end
-
-    def endpoint_for_request(request)
-      @spec
-        .path_by_path(request.path)
-        .endpoint_by_method(request.request_method.downcase)
-    rescue OasParser::PathNotFound
-      nil
+    def endpoint_id(operation)
+      "#{operation.path.path}##{operation.method}"
     end
   end
 end

data/lib/openapi_first/definition.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  class Definition
+    def initialize(parsed)
+      @spec = parsed
+    end
+
+    def operations
+      @spec.endpoints
+    end
+
+    def find_operation!(request)
+      @spec
+        .path_by_path(request.path)
+        .endpoint_by_method(request.request_method.downcase)
+    end
+
+    def find_operation(request)
+      find_operation!(request)
+    rescue OasParser::PathNotFound, OasParser::MethodNotFound
+      nil
+    end
+  end
+end

data/lib/openapi_first/response_validator.rb

@@ -6,8 +6,8 @@ require_relative 'validation'
 
 module OpenapiFirst
   class ResponseValidator
-    def initialize(schema)
-      @schema = schema
+    def initialize(spec)
+      @spec = spec
     end
 
     def validate(request, response)
@@ -20,7 +20,7 @@ module OpenapiFirst
     private
 
     def validation_errors(request, response)
-      content = response_for(request, response).content
+      content = response_for(request, response)&.content
       return unless content
 
       content_type = content[response.content_type]
@@ -37,16 +37,23 @@ module OpenapiFirst
 
     def validate_json_schema(schema, data)
       JSONSchemer.schema(schema).validate(data).to_a.map do |error|
-        error.delete('root_schema')
-        error
+        format_error(error)
+      end
+    end
+
+    def format_error(error)
+      ValidationFormat.error_details(error)
+                      .merge!(
+                        data_pointer: error['data_pointer'],
+                        schema_pointer: error['schema_pointer']
+                      ).tap do |formatted|
       end
     end
 
     def response_for(request, response)
-      @schema
-        .path_by_path(request.path)
-        .endpoint_by_method(request.request_method.downcase)
-        .response_by_code(response.status.to_s, use_default: true)
+      @spec
+        .find_operation!(request)
+        &.response_by_code(response.status.to_s, use_default: true)
     end
   end
 end

data/lib/openapi_first/router.rb

@@ -15,7 +15,7 @@ module OpenapiFirst
 
     def call(env)
       req = Rack::Request.new(env)
-      operation = env[OPERATION] = find_operation(req)
+      operation = env[OPERATION] = @spec.find_operation(req)
       path_params = find_path_params(operation, req)
       env[PATH_PARAMS] = path_params if path_params
       return @app.call(env) if operation || @allow_unknown_operation
@@ -23,13 +23,6 @@ module OpenapiFirst
       Rack::Response.new('', 404)
     end
 
-    def find_operation(req)
-      path = @spec.path_by_path(req.path)
-      path.endpoint_by_method(req.request_method.downcase)
-    rescue OasParser::PathNotFound, OasParser::MethodNotFound
-      nil
-    end
-
     def find_path_params(operation, req)
       return unless operation&.path_parameters&.any?
 

data/lib/openapi_first/validation_format.rb

@@ -2,6 +2,8 @@
 
 module OpenapiFirst
   module ValidationFormat
+    SIMPLE_TYPES = %w[string integer].freeze
+
     # rubocop:disable Metrics/MethodLength
     def self.error_details(error)
       if error['type'] == 'pattern'
@@ -14,6 +16,10 @@ module OpenapiFirst
         {
           title: "is missing required properties: #{missing_keys.join(', ')}"
         }
+      elsif SIMPLE_TYPES.include?(error['type'])
+        {
+          title: "should be a #{error['type']}"
+        }
       elsif error['schema'] == false
         { title: 'unknown fields are not allowed' }
       else

data/lib/openapi_first/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenapiFirst
-  VERSION = '0.6.0'
+  VERSION = '0.6.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: openapi_first
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Andreas Haller
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-07-07 00:00:00.000000000 Z
+date: 2019-07-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json_schemer
@@ -148,6 +148,7 @@ files:
 - lib/openapi_first.rb
 - lib/openapi_first/app.rb
 - lib/openapi_first/coverage.rb
+- lib/openapi_first/definition.rb
 - lib/openapi_first/error_response_method.rb
 - lib/openapi_first/operation_resolver.rb
 - lib/openapi_first/query_parameter_validation.rb