openapi_first 1.1.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bb6d0ee4dbe98020ef124e79a99ced0d0111b1e2891cc8cb3ed8bb697973d2b
-  data.tar.gz: 77ce896a68f885614f64fd680af0dde1860c07ae772ce7d5f7d1b75b5abb4528
+  metadata.gz: caea1ca3e63935e0d04a52bade49e9f8270da3bdcf3b3cb89e3791cc202c1a79
+  data.tar.gz: 3d1da5e269e0328ec383b30cf29486b1d49aa91317e428626c26f9284eb1d55c
 SHA512:
-  metadata.gz: 841e32068646969d92ab26fff9c332e849056463c99805c8e0dbbb437918113a09750fb5ceffd3940716911ea50bc20685acbcd862aa6acc270e43fe43675c87
-  data.tar.gz: d9a225b3e3119512fc3ed585f00f6f915e21f3199206f520d20733999441567e651fcb129588092c4e7ea9dcc4ce1e77c24365b04b8a8d9d232b8a1a5cd8e1da
+  metadata.gz: 0a48588e004db687e0dee2b54982837aebe3dcb3d65cf3191141b59d7f63d945083dd0bc364346acaa4442420101310ffc174383ee6e2897468b6680f90c4172
+  data.tar.gz: 352789bc86107fc3253cb08a3771399e5ecee50189c119903bc678f1de7eb078a6bc89a797bc22322ae52beb3de30c64de612fb6350d572cc6a6a1c1cb6fd067

data/lib/openapi_first/body_parser.rb

@@ -3,10 +3,12 @@
 require 'multi_json'
 
 module OpenapiFirst
+  # @!visibility private
   class BodyParser
     def self.const_missing(const_name)
       super unless const_name == :ParsingError
-      warn 'DEPRECATION WARNING: OpenapiFirst::BodyParser::ParsingError is deprecated. Use OpenapiFirst::ParseError instead.' # rubocop:disable Layout/LineLength
+      warn 'DEPRECATION WARNING: OpenapiFirst::BodyParser::ParsingError is deprecated. ' \
+           'Use OpenapiFirst::ParseError instead.'
       OpenapiFirst::ParseError
     end
 

data/lib/openapi_first/configuration.rb

@@ -1,13 +1,15 @@
 # frozen_string_literal: true
 
 module OpenapiFirst
+  # Global configuration. Currently only used for the request validation middleware.
   class Configuration
     def initialize
       @request_validation_error_response = OpenapiFirst.plugin(:default)::ErrorResponse
       @request_validation_raise_error = false
     end
 
-    attr_reader :request_validation_error_response, :request_validation_raise_error
+    attr_reader :request_validation_error_response
+    attr_accessor :request_validation_raise_error
 
     def request_validation_error_response=(mod)
       @request_validation_error_response = if mod.is_a?(Symbol)

data/lib/openapi_first/definition/operation.rb

@@ -8,11 +8,14 @@ require_relative 'responses'
 
 module OpenapiFirst
   class Definition
+    # Represents an operation object in the OpenAPI 3.X specification.
+    # Use this class to access information about the operation. Use `#[key]` to read the raw data.
+    # When using the middleware you can access the operation object via `env[OpenapiFirst::REQUEST].operation`.
     class Operation
       extend Forwardable
+
       def_delegators :operation_object,
-                     :[],
-                     :dig
+                     :[]
 
       WRITE_METHODS = Set.new(%w[post put patch delete]).freeze
       private_constant :WRITE_METHODS
@@ -25,31 +28,62 @@ module OpenapiFirst
         @operation_object = @path_item_object[request_method]
       end
 
-      attr_reader :path, :method, :openapi_version
+      # Returns the path of the operation as in the API description.
+      # @return [String] The path of the operation.
+      attr_reader :path
+
+      # Returns the (downcased) request method of the operation.
+      # Example: "get"
+      # @return [String] The request method of the operation.
+      attr_reader :method
       alias request_method method
 
+      attr_reader :openapi_version # :nodoc:
+
+      # Returns the operation ID as defined in the API description.
+      # @return [String, nil]
       def operation_id
         operation_object['operationId']
       end
 
+      # Checks if the operation is a read operation.
+      # This is the case for all request methods except POST, PUT, PATCH and DELETE.
+      # @return [Boolean] `true` if the operation is a read operation, `false` otherwise.
       def read?
         !write?
       end
 
+      # Checks if the operation is a write operation.
+      # This is the case for POST, PUT, PATCH and DELETE request methods.
+      # @return [Boolean] `true` if the operation is a write operation, `false` otherwise.
       def write?
         WRITE_METHODS.include?(method)
       end
 
+      # Returns the request body definition if defined in the API description.
+      # @return [RequestBody, nil] The request body of the operation, or `nil` if not present.
       def request_body
         @request_body ||= RequestBody.new(operation_object['requestBody'], self) if operation_object['requestBody']
       end
 
+      # Checks if a response status is defined for this operation.
+      # @param status [Integer, String] The response status to check.
+      # @return [Boolean] `true` if the response status is defined, `false` otherwise.
       def response_status_defined?(status)
         responses.status_defined?(status)
       end
 
-      def_delegators :responses, :response_for
+      # Returns the response object for a given status.
+      # @param status [Integer, String] The response status.
+      # @param content_type [String] Content-Type of the current response.
+      # @return [Response, nil] The response object for the given status, or `nil` if not found.
+      def response_for(status, content_type)
+        responses.response_for(status, content_type)
+      end
 
+      # Returns the schema for a given content type.
+      # @param content_type [String] The content type.
+      # @return [Schema, nil] The schema for the given content type, or `nil` if not found.
       def schema_for(content_type)
         content = @request_body_object['content']
         return unless content&.any?
@@ -60,46 +94,72 @@ module OpenapiFirst
         end
       end
 
+      # Returns a unique name for this operation. Used for generating error messages.
+      # @visibility private
       def name
         @name ||= "#{method.upcase} #{path} (#{operation_id})"
       end
 
+      # Returns the path parameters of the operation.
+      # @return [Array<Hash>] The path parameters of the operation.
       def path_parameters
         all_parameters['path']
       end
 
+      # Returns the query parameters of the operation.
+      # Returns parameters defined on the path and in the operation.
+      # @return [Array<Hash>] The query parameters of the operation.
       def query_parameters
         all_parameters['query']
       end
 
+      # Returns the header parameters of the operation.
+      # Returns parameters defined on the path and in the operation.
+      # @return [Array<Hash>] The header parameters of the operation.
       def header_parameters
         all_parameters['header']
       end
 
+      # Returns the cookie parameters of the operation.
+      # Returns parameters defined on the path and in the operation.
+      # @return [Array<Hash>] The cookie parameters of the operation.
       def cookie_parameters
         all_parameters['cookie']
       end
 
+      # Returns the schema for the path parameters.
+      # @visibility private
+      # @return [Schema, nil] The schema for the path parameters, or `nil` if not found.
       def path_parameters_schema
         @path_parameters_schema ||= build_schema(path_parameters)
       end
 
+      # Returns the schema for the query parameters.
+      # @visibility private
+      # @return [Schema, nil] The schema for the query parameters, or `nil` if not found.
       def query_parameters_schema
         @query_parameters_schema ||= build_schema(query_parameters)
       end
 
+      # Returns the schema for the header parameters.
+      # @visibility private
+      # @return [Schema, nil] The schema for the header parameters, or `nil` if not found.
       def header_parameters_schema
         @header_parameters_schema ||= build_schema(header_parameters)
       end
 
+      # Returns the schema for the cookie parameters.
+      # @visibility private
+      # @return [Schema, nil] The schema for the cookie parameters, or `nil` if not found.
       def cookie_parameters_schema
         @cookie_parameters_schema ||= build_schema(cookie_parameters)
       end
 
       private
 
+      WRITE_METHODS = Set.new(%w[post put patch delete]).freeze
+
       IGNORED_HEADERS = Set['Content-Type', 'Accept', 'Authorization'].freeze
-      private_constant :IGNORED_HEADERS
 
       def all_parameters
         @all_parameters ||= (@path_item_object.fetch('parameters', []) + operation_object.fetch('parameters', []))

data/lib/openapi_first/definition/path_item.rb

@@ -4,6 +4,7 @@ require_relative 'operation'
 
 module OpenapiFirst
   class Definition
+    # A pathItem as defined in the OpenAPI document.
     class PathItem
       def initialize(path, path_item_object, openapi_version:)
         @path = path

data/lib/openapi_first/definition/request_body.rb

@@ -4,6 +4,7 @@ require_relative '../schema'
 
 module OpenapiFirst
   class Definition
+    # Represents a request body definition in the OpenAPI document that belongs to an operation.
     class RequestBody
       def initialize(request_body_object, operation)
         @request_body_object = request_body_object

data/lib/openapi_first/definition/response.rb

@@ -2,6 +2,9 @@
 
 module OpenapiFirst
   class Definition
+    # Represents a response definition in the OpenAPI document.
+    # This is not a direct reflecton of the OpenAPI 3.X response definition, but a combination of
+    # status, content type and content schema.
     class Response
       def initialize(operation:, status:, response_object:, content_type:, content_schema:)
         @operation = operation
@@ -11,6 +14,10 @@ module OpenapiFirst
         @content_schema = content_schema
       end
 
+      # @attr_reader [Operation] operation The operation this response belongs to.
+      # @attr_reader [Integer] status The HTTP status code of the response definition.
+      # @attr_reader [String, nil] content_type Content type of this response.
+      # @attr_reader [Schema, nil] content_schema the Schema of the response body.
       attr_reader :operation, :status, :content_type, :content_schema
 
       def headers

data/lib/openapi_first/definition.rb

@@ -1,20 +1,47 @@
 # frozen_string_literal: true
 
-require 'mustermann/template'
+require 'mustermann'
 require_relative 'definition/path_item'
 require_relative 'runtime_request'
+require_relative 'request_validation/validator'
+require_relative 'response_validation/validator'
 
 module OpenapiFirst
   # Represents an OpenAPI API Description document
+  # This is returned by OpenapiFirst.load.
   class Definition
     attr_reader :filepath, :paths, :openapi_version
 
-    def initialize(resolved, filepath)
+    # @param resolved [Hash] The resolved OpenAPI document.
+    # @param filepath [String] The file path of the OpenAPI document.
+    def initialize(resolved, filepath = nil)
       @filepath = filepath
       @paths = resolved['paths']
       @openapi_version = detect_version(resolved)
     end
 
+    # Validates the request against the API description.
+    # @param rack_request [Rack::Request] The Rack request object.
+    # @param raise_error [Boolean] Whether to raise an error if validation fails.
+    # @return [RuntimeRequest] The validated request object.
+    def validate_request(rack_request, raise_error: false)
+      validated = request(rack_request).tap(&:validate)
+      validated.error&.raise! if raise_error
+      validated
+    end
+
+    # Validates the response against the API description.
+    # @param rack_request [Rack::Request] The Rack request object.
+    # @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_request, rack_response, raise_error: false)
+      request(rack_request).validate_response(rack_response, raise_error:)
+    end
+
+    # Builds a RuntimeRequest object based on the Rack request.
+    # @param rack_request [Rack::Request] The Rack request object.
+    # @return [RuntimeRequest] The RuntimeRequest object.
     def request(rack_request)
       path_item, path_params = find_path_item_and_params(rack_request.path)
       operation = path_item&.operation(rack_request.request_method.downcase)
@@ -26,14 +53,25 @@ module OpenapiFirst
       )
     end
 
+    # Builds a RuntimeResponse object based on the Rack request and response.
+    # @param rack_request [Rack::Request] The Rack request object.
+    # @param rack_response [Rack::Response] The Rack response object.
+    # @return [RuntimeResponse] The RuntimeResponse object.
     def response(rack_request, rack_response)
       request(rack_request).response(rack_response)
     end
 
+    # Gets all the operations defined in the API description.
+    # @return [Array<Operation>] An array of Operation objects.
     def operations
       @operations ||= path_items.flat_map(&:operations)
     end
 
+    # Gets the PathItem object for the specified path.
+    # @param pathname [String] The path template string.
+    # @return [PathItem] The PathItem object.
+    # Example:
+    #   definition.path('/pets/{id}')
     def path(pathname)
       return unless paths.key?(pathname)
 
@@ -42,6 +80,8 @@ module OpenapiFirst
 
     private
 
+    # Gets all the PathItem objects defined in the API description.
+    # @return [Array] An array of PathItem objects.
     def path_items
       @path_items ||= paths.flat_map do |path, path_item_object|
         PathItem.new(path, path_item_object, openapi_version:)
@@ -60,7 +100,7 @@ module OpenapiFirst
 
     def search_for_path_item(request_path)
       paths.find do |path, path_item_object|
-        template = Mustermann::Template.new(path)
+        template = Mustermann.new(path)
         path_params = template.params(request_path)
         next unless path_params
         next unless path_params.size == template.names.size

data/lib/openapi_first/error_response.rb

@@ -29,7 +29,7 @@ module OpenapiFirst
 
     # The response status
     def status
-      STATUS[failure.error_type] || 400
+      STATUS[failure.type] || 400
     end
 
     # Render this error response

data/lib/openapi_first/errors.rb

@@ -1,10 +1,16 @@
 # frozen_string_literal: true
 
 module OpenapiFirst
+  # @!visibility private
   class Error < StandardError; end
+  # @!visibility private
   class ParseError < Error; end
+  # @!visibility private
   class NotFoundError < Error; end
+  # @!visibility private
   class RequestInvalidError < Error; end
+  # @!visibility private
   class ResponseNotFoundError < Error; end
+  # @!visibility private
   class ResponseInvalidError < Error; end
 end

data/lib/openapi_first/failure.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module OpenapiFirst
+  # A failure object returned when validation of request or response has failed.
   class Failure
     FAILURE = :openapi_first_validation_failure
 
@@ -29,7 +30,7 @@ module OpenapiFirst
       )
     end
 
-    # @param type [Symbol] See TYPES.keys
+    # @param error_type [Symbol] See TYPES.keys
     # @param message [String] A generic error message
     # @param errors [Array<OpenapiFirst::Schema::ValidationError>]
     def initialize(error_type, message: nil, errors: nil)
@@ -43,13 +44,36 @@ module OpenapiFirst
       @errors = errors
     end
 
-    attr_reader :error_type, :message, :errors
+    # @attr_reader [Symbol] error_type The type of the failure. See TYPES.keys.
+    # @alias type error_type
+    # Example: :invalid_body
+    attr_reader :error_type
+    alias type error_type
+
+    # @attr_reader [String] message A generic error message
+    attr_reader :message
+
+    # @attr_reader [Array<OpenapiFirst::Schema::ValidationError>] errors Schema validation errors
+    attr_reader :errors
 
     # Raise an exception that fits the failure.
     def raise!
-      exception, message_prefix = TYPES.fetch(error_type)
+      exception, = TYPES.fetch(error_type)
+      raise exception, exception_message
+    end
+
+    def exception_message
+      _, message_prefix = TYPES.fetch(error_type)
+
+      "#{message_prefix} #{@message || generate_message}"
+    end
+
+    private
 
-      raise exception, "#{message_prefix} #{@message || errors&.map(&:error)&.join('. ')}"
+    def generate_message
+      messages = errors&.take(4)&.map(&:error)
+      messages << "... (#{errors.size} errors total)" if errors && errors.size > 4
+      messages&.join('. ')
     end
   end
 end

data/lib/openapi_first/middlewares/request_validation.rb

@@ -26,11 +26,8 @@ module OpenapiFirst
         request = find_request(env)
         return @app.call(env) unless request
 
-        failure = if @raise
-                    request.validate!
-                  else
-                    request.validate
-                  end
+        failure = request.validate
+        failure.raise! if failure && @raise
         return @error_response_class.new(failure:).render if failure
 
         @app.call(env)

data/lib/openapi_first/middlewares/response_validation.rb

@@ -20,11 +20,8 @@ module OpenapiFirst
       def call(env)
         request = find_request(env)
         status, headers, body = @app.call(env)
-
         body = body.to_ary if body.respond_to?(:to_ary)
-
-        request.response(Rack::Response[status, headers, body]).validate!
-
+        request.validate_response(Rack::Response[status, headers, body], raise_error: true)
         [status, headers, body]
       end
 

data/lib/openapi_first/plugins/default/error_response.rb

@@ -29,10 +29,10 @@ module OpenapiFirst
           MultiJson.dump(result)
         end
 
-        def error_type = failure.error_type
+        def type = failure.type
 
         def title
-          TITLES.fetch(error_type)
+          TITLES.fetch(type)
         end
 
         def content_type
@@ -51,7 +51,7 @@ module OpenapiFirst
         end
 
         def pointer_key
-          case error_type
+          case type
           when :invalid_body
             :pointer
           when :invalid_query, :invalid_path
@@ -64,7 +64,7 @@ module OpenapiFirst
         end
 
         def pointer(data_pointer)
-          return data_pointer if error_type == :invalid_body
+          return data_pointer if type == :invalid_body
 
           data_pointer.delete_prefix('/')
         end

data/lib/openapi_first/plugins/default.rb

@@ -4,7 +4,7 @@ require_relative 'default/error_response'
 
 module OpenapiFirst
   module Plugins
-    module Default
+    module Default # :nodoc:
       OpenapiFirst.register(:default, self)
     end
   end

data/lib/openapi_first/plugins/jsonapi/error_response.rb

@@ -3,6 +3,7 @@
 module OpenapiFirst
   module Plugins
     module Jsonapi
+      # A JSON:API conform error response. See https://jsonapi.org/.
       class ErrorResponse
         include OpenapiFirst::ErrorResponse
 
@@ -36,7 +37,7 @@ module OpenapiFirst
         end
 
         def pointer_key
-          case failure.error_type
+          case failure.type
           when :invalid_body
             :pointer
           when :invalid_query, :invalid_path
@@ -49,7 +50,7 @@ module OpenapiFirst
         end
 
         def pointer(data_pointer)
-          return data_pointer if failure.error_type == :invalid_body
+          return data_pointer if failure.type == :invalid_body
 
           data_pointer.delete_prefix('/')
         end

data/lib/openapi_first/plugins/jsonapi.rb

@@ -4,7 +4,7 @@ require_relative 'jsonapi/error_response'
 
 module OpenapiFirst
   module Plugins
-    module Jsonapi
+    module Jsonapi # :nodoc:
       OpenapiFirst.register(:jsonapi, self)
     end
   end

data/lib/openapi_first/plugins.rb

@@ -4,6 +4,7 @@ module OpenapiFirst
   # Plugin System adapted from
   # Polished Ruby Programming by Jeremy Evans
   # https://itunes.apple.com/WebObjects/MZStore.woa/wa/viewBook?id=0
+  # @!visibility private
   module Plugins
     PLUGINS = {} # rubocop:disable Style/MutableConstant
 

data/lib/openapi_first/request_validation/request_body_validator.rb

@@ -4,7 +4,7 @@ require_relative '../failure'
 
 module OpenapiFirst
   module RequestValidation
-    class RequestBodyValidator
+    class RequestBodyValidator # :nodoc:
       def initialize(operation)
         @operation = operation
       end

data/lib/openapi_first/request_validation/validator.rb

@@ -5,6 +5,7 @@ require_relative 'request_body_validator'
 
 module OpenapiFirst
   module RequestValidation
+    # Validates a RuntimeRequest against an Operation.
     class Validator
       def initialize(operation)
         @operation = operation

data/lib/openapi_first/response_validation/validator.rb

@@ -4,6 +4,7 @@ require_relative '../failure'
 
 module OpenapiFirst
   module ResponseValidation
+    # Validates a RuntimeResponse against an Operation.
     class Validator
       def initialize(operation)
         @operation = operation