openapi_first 1.1.1 → 1.3.0

data/lib/openapi_first/runtime_request.rb

@@ -16,31 +16,59 @@ module OpenapiFirst
       @path_item = path_item
       @operation = operation
       @original_path_params = path_params
+      @error = nil
+      @validated = false
     end
 
     def_delegators :@request, :content_type, :media_type, :path
     def_delegators :@operation, :operation_id, :request_method
     def_delegator :@path_item, :path, :path_definition
 
+    # Returns the path_item object.
+    # @return [PathItem, nil] The path_item object or nil if this request path is not known.
     attr_reader :path_item
 
+    # Returns the operation object.
+    # @return [Operation, nil] The operation object or nil if this request method is not known.
+    attr_reader :operation
+
+    # Returns the error object if validation failed.
+    # @return [Failure, nil]
+    attr_reader :error
+
+    # Checks if the request is valid.
+    # @return [Boolean] true if the request is valid, false otherwise.
+    def valid?
+      validate unless @validated
+      error.nil?
+    end
+
+    # Checks if the path and request method are known.
+    # @return [Boolean] true if the path and request method are known, false otherwise.
     def known?
       known_path? && known_request_method?
     end
 
+    # Checks if the path is known.
+    # @return [Boolean] true if the path is known, false otherwise.
     def known_path?
       !!path_item
     end
 
+    # Checks if the request method is known.
+    # @return [Boolean] true if the request method is known, false otherwise.
     def known_request_method?
       !!operation
     end
 
-    # Merged path and query parameters
+    # Returns the merged path and query parameters.
+    # @return [Hash] The merged path and query parameters.
     def params
       @params ||= query.merge(path_parameters)
     end
 
+    # Returns the parsed path parameters of the request.
+    # @return [Hash]
     def path_parameters
       return {} unless operation.path_parameters
 
@@ -48,6 +76,10 @@ module OpenapiFirst
         OpenapiParameters::Path.new(operation.path_parameters).unpack(@original_path_params) || {}
     end
 
+    # Returns the parsed query parameters.
+    # This only includes parameters that are defined in the API description.
+    # @note This method is aliased as query_parameters.
+    # @return [Hash]
     def query
       return {} unless operation.query_parameters
 
@@ -57,12 +89,18 @@ module OpenapiFirst
 
     alias query_parameters query
 
+    # Returns the parsed header parameters.
+    # This only includes parameters that are defined in the API description.
+    # @return [Hash]
     def headers
       return {} unless operation.header_parameters
 
       @headers ||= OpenapiParameters::Header.new(operation.header_parameters).unpack_env(request.env) || {}
     end
 
+    # Returns the parsed cookie parameters.
+    # This only includes parameters that are defined in the API description.
+    # @return [Hash]
     def cookies
       return {} unless operation.cookie_parameters
 
@@ -70,26 +108,48 @@ module OpenapiFirst
         OpenapiParameters::Cookie.new(operation.cookie_parameters).unpack(request.env[Rack::HTTP_COOKIE]) || {}
     end
 
+    # Returns the parsed request body.
+    # This returns the whole request body with default values applied as defined in the API description.
+    # This does not remove any fields that are not defined in the API description.
+    # @return [Hash, Array, String, nil] The parsed body of the request.
     def body
       @body ||= BodyParser.new.parse(request, request.media_type)
     end
+
     alias parsed_body body
 
+    # Validates the request.
+    # @return [Failure, nil] The Failure object if validation failed.
     def validate
-      RequestValidation::Validator.new(operation).validate(self)
+      @validated = true
+      @error = RequestValidation::Validator.new(operation).validate(self)
     end
 
+    # Validates the request and raises an error if validation fails.
     def validate!
       error = validate
       error&.raise!
     end
 
+    # Validates the response.
+    # @param rack_response [Rack::Response] The rack response object.
+    # @param raise_error [Boolean] Whether to raise an error if validation fails.
+    # @return [RuntimeResponse] The validated response object.
+    def validate_response(rack_response, raise_error: false)
+      validated = response(rack_response).tap(&:validate)
+      validated.error&.raise! if raise_error
+      validated
+    end
+
+    # Creates a new RuntimeResponse object.
+    # @param rack_response [Rack::Response] The rack response object.
+    # @return [RuntimeResponse] The RuntimeResponse object.
     def response(rack_response)
       RuntimeResponse.new(operation, rack_response)
     end
 
     private
 
-    attr_reader :request, :operation
+    attr_reader :request
   end
 end

data/lib/openapi_first/runtime_response.rb

@@ -5,56 +5,95 @@ require_relative 'body_parser'
 require_relative 'response_validation/validator'
 
 module OpenapiFirst
+  # Represents a response returned by the Rack application and how it relates to the API description.
   class RuntimeResponse
     extend Forwardable
 
     def initialize(operation, rack_response)
       @operation = operation
       @rack_response = rack_response
+      @error = nil
     end
 
+    # @return [Failure, nil] Error object if validation failed.
+    attr_reader :error
+
+    # @attr_reader [Integer] status The HTTP status code of this response.
+    # @attr_reader [String] content_type The content_type of the Rack::Response.
     def_delegators :@rack_response, :status, :content_type
-    def_delegators :@operation, :name
 
+    # @attr_reader [String] name The name of the operation. Used for generating error messages.
+    def_delegators :@operation, :name # @visibility private
+
+    # Checks if the response is valid. Runs the validation unless it has been run before.
+    # @return [Boolean]
+    def valid?
+      validate unless @validated
+      @error.nil?
+    end
+
+    # Checks if the response is defined in the API description.
+    # @return [Boolean] Returns true if the response is known, false otherwise.
     def known?
       !!response_definition
     end
 
+    # Checks if the response status is defined in the API description.
+    # @return [Boolean] Returns true if the response status is known, false otherwise.
     def known_status?
       @operation.response_status_defined?(status)
     end
 
+    # Returns the description of the response definition if available.
+    # @return [String, nil] Returns the description of the response, or nil if not available.
     def description
       response_definition&.description
     end
 
+    # Returns the parsed (JSON) body of the response.
+    # @return [Hash, String] Returns the body of the response.
     def body
       @body ||= content_type =~ /json/i ? load_json(original_body) : original_body
     end
 
+    # Returns the headers of the response as defined in the API description.
+    # This only returns the headers that are defined in the API description.
+    # @return [Hash] Returns the headers of the response.
     def headers
       @headers ||= unpack_response_headers
     end
 
+    # Validates the response.
+    # @return [Failure, nil] Returns the validation error, or nil if the response is valid.
     def validate
-      ResponseValidation::Validator.new(@operation).validate(self)
+      @validated = true
+      @error = ResponseValidation::Validator.new(@operation).validate(self)
     end
 
+    # Validates the response and raises an error if invalid.
+    # @raise [ResponseNotFoundError, ResponseInvalidError] Raises an error if the response is invalid.
     def validate!
       error = validate
       error&.raise!
     end
 
+    # Returns the response definition associated with the response.
+    # @return [Definition::Response, nil] Returns the response definition, or nil if not found.
     def response_definition
       @response_definition ||= @operation.response_for(status, content_type)
     end
 
     private
 
+    # Usually the body responds to #each, but when using manual response validation without the middleware
+    # in Rails request specs the body is a String. So this code handles both cases.
     def original_body
       buffered_body = String.new
-      @rack_response.body.each { |chunk| buffered_body << chunk }
-      buffered_body
+      if @rack_response.body.respond_to?(:each)
+        @rack_response.body.each { |chunk| buffered_body.to_s << chunk }
+        return buffered_body
+      end
+      @rack_response.body
     end
 
     def load_json(string)

data/lib/openapi_first/schema/validation_error.rb

@@ -2,12 +2,14 @@
 
 module OpenapiFirst
   class Schema
+    # One of multiple validation errors. Returned by Schema::ValidationResult#errors.
     class ValidationError
       def initialize(json_schemer_error)
         @error = json_schemer_error
       end
 
       def error = @error['error']
+      alias message error
       def schemer_error = @error
       def instance_location = @error['data_pointer']
       def schema_location = @error['schema_pointer']

data/lib/openapi_first/schema/validation_result.rb

@@ -4,6 +4,7 @@ require_relative 'validation_error'
 
 module OpenapiFirst
   class Schema
+    # Result of validating data against a schema. Return value of Schema#validate.
     class ValidationResult
       def initialize(validation, schema:, data:)
         @validation = validation
@@ -15,18 +16,12 @@ module OpenapiFirst
 
       def error? = @validation.any?
 
+      # Returns an array of ValidationError objects.
       def errors
         @errors ||= @validation.map do |err|
           ValidationError.new(err)
         end
       end
-
-      # Returns a message that is used in exception messages.
-      def message
-        return unless error?
-
-        errors.map(&:error).join('. ')
-      end
     end
   end
 end

data/lib/openapi_first/schema.rb

@@ -4,6 +4,7 @@ require 'json_schemer'
 require_relative 'schema/validation_result'
 
 module OpenapiFirst
+  # Validate data via JSON Schema. A wrapper around JSONSchemer.
   class Schema
     attr_reader :schema
 

data/lib/openapi_first/version.rb

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

data/lib/openapi_first.rb

@@ -12,14 +12,18 @@ require_relative 'openapi_first/error_response'
 require_relative 'openapi_first/middlewares/response_validation'
 require_relative 'openapi_first/middlewares/request_validation'
 
+# OpenapiFirst is a toolchain to build HTTP APIS based on OpenAPI API descriptions.
 module OpenapiFirst
   extend Plugins
 
   class << self
+    # @return [Configuration]
     def configuration
       @configuration ||= Configuration.new
     end
 
+    # @return [Configuration]
+    # @yield [Configuration]
     def configure
       yield configuration
     end
@@ -28,12 +32,26 @@ module OpenapiFirst
   # Key in rack to find instance of RuntimeRequest
   REQUEST = 'openapi.request'
 
-  def self.load(spec_path, only: nil)
-    resolved = Bundle.resolve(spec_path)
+  # Load and dereference an OpenAPI spec file
+  # @return [Definition]
+  def self.load(filepath, only: nil)
+    resolved = bundle(filepath)
+    parse(resolved, only:, filepath:)
+  end
+
+  # Parse a dereferenced Hash
+  # @return [Definition]
+  def self.parse(resolved, only: nil, filepath: nil)
     resolved['paths'].filter!(&->(key, _) { only.call(key) }) if only
-    Definition.new(resolved, spec_path)
+    Definition.new(resolved, filepath)
+  end
+
+  # @!visibility private
+  def self.bundle(filepath)
+    Bundle.resolve(filepath)
   end
 
+  # @!visibility private
   module Bundle
     def self.resolve(spec_path)
       Dir.chdir(File.dirname(spec_path)) do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: openapi_first
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.3.0
 platform: ruby
 authors:
 - Andreas Haller
 autorequire:
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2024-01-12 00:00:00.000000000 Z
+date: 2024-01-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json_refs
@@ -59,7 +59,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.15'
 - !ruby/object:Gem::Dependency
-  name: mustermann-contrib
+  name: mustermann
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -119,16 +119,6 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".github/CODEOWNERS"
-- ".github/workflows/ruby.yml"
-- ".gitignore"
-- CHANGELOG.md
-- Gemfile
-- Gemfile.lock
-- Gemfile.rack2
-- Gemfile.rack2.lock
-- LICENSE.txt
-- README.md
 - lib/openapi_first.rb
 - lib/openapi_first/body_parser.rb
 - lib/openapi_first/configuration.rb
@@ -157,12 +147,11 @@ files:
 - lib/openapi_first/schema/validation_error.rb
 - lib/openapi_first/schema/validation_result.rb
 - lib/openapi_first/version.rb
-- openapi_first.gemspec
 homepage: https://github.com/ahx/openapi_first
 licenses:
 - MIT
 metadata:
-  https://github.com/ahx/openapi_first: https://github.com/ahx/openapi_first
+  homepage_uri: https://github.com/ahx/openapi_first
   source_code_uri: https://github.com/ahx/openapi_first
   changelog_uri: https://github.com/ahx/openapi_first/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
@@ -184,5 +173,5 @@ requirements: []
 rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
-summary: Implement REST APIs based on OpenApi 3.x
+summary: Implement HTTP APIs based on OpenApi 3.x
 test_files: []

data/.github/CODEOWNERS

@@ -1 +0,0 @@
-* @ahx

data/.github/workflows/ruby.yml

@@ -1,13 +0,0 @@
-name: Test
-on: [push, pull_request]
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v3
-    - uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: '3.1'
-        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
-    - run: BUNDLE_GEMFILE=Gemfile bundle exec rake
-    - run: BUNDLE_GEMFILE=Gemfile.rack2 bundle lock --add-platform x86_64-linux && bundle exec rake

data/.gitignore

@@ -1,11 +0,0 @@
-/.bundle/
-/.yardoc
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-/tmp/
-
-# rspec failure tracking
-.rspec_status