openapi_first 1.2.1 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ee379d839bec13bd899f690b3275d761b7425461f2241da4ccb62de384f0c94
-  data.tar.gz: 6ea27d437c7cb443d5b5c84b8e6d0ef34782e4f5d8bb5ce7666acc78797ca523
+  metadata.gz: f7e9e0bad95211ba2b4f103089abc40d0e7fc46a24f7ce8e57318ba489655637
+  data.tar.gz: f1d28fbaa79a4eb7e00b242eb9bd89a78789bbb04742e0b87501ac454fb1cf47
 SHA512:
-  metadata.gz: ab20a8bcd7d61961f4a1d654a36291f295ee0d69c50829cd8f1965998ca9a480a0636e2b0ca62d220a53c62b60d8bedb934fc8a57bed39a8e45683796a5cee8a
-  data.tar.gz: 43206c1bf540193863bd1f02c14f79d172fff662974c8efbfd90dfd6334f11f23c0dee62c9c70c4bd45bbf202e68a76c9750a00aa4a45f5dd8682b6837a1177b
+  metadata.gz: f225e3a49d7f582e0f82822b2c9acbcd6008b6cc2464971e1485ef75ec12e508effc2165b6afc91535e27bc9bb9004f92fb160218f7295b0f45c3f58946ed616
+  data.tar.gz: 4c6ef209df4816361bed148f33b4e55ace50a5481172913c5760d014b09247adf74ffdbd2422ae930cd889494fe941c20d492835863d52a9dde67a75c1bd8622

data/lib/openapi_first/body_parser.rb

@@ -3,6 +3,7 @@
 require 'multi_json'
 
 module OpenapiFirst
+  # @!visibility private
   class BodyParser
     def self.const_missing(const_name)
       super unless const_name == :ParsingError

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,14 +8,15 @@ 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,
                      :[]
 
-      WRITE_METHODS = Set.new(%w[post put patch delete]).freeze
-      private_constant :WRITE_METHODS
-
       def initialize(path, request_method, path_item_object, openapi_version:)
         @path = path
         @method = request_method
@@ -24,31 +25,63 @@ 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.
+      # @deprecated Use {#write?} instead.
       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?
@@ -59,44 +92,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
+      private_constant :WRITE_METHODS
+
       IGNORED_HEADERS = Set['Content-Type', 'Accept', 'Authorization'].freeze
       private_constant :IGNORED_HEADERS
 

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
@@ -36,7 +37,7 @@ module OpenapiFirst
           schema_object = media_type['schema']
           next unless schema_object
 
-          result[type] = Schema.new(schema_object, write: @operation.write?,
+          result[type] = Schema.new(schema_object, write: true,
                                                    openapi_version: @operation.openapi_version)
         end
       end

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

@@ -3,18 +3,45 @@
 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
 
+    # @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:)

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,7 +44,17 @@ 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!

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

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
 
-    attr_reader :path_item, :operation
+    # 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,20 +108,42 @@ 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