jsapi 0.1.1 → 0.1.2

data/lib/jsapi/dsl/schema.rb

@@ -5,24 +5,82 @@ module Jsapi
     # Used to specify details of a schema.
     class Schema < Node
 
-      # Includes all of the properties from +schemas+. Each argument must
-      # be the name of a schema defined by ClassMethods#api_schema or
-      # Definitions#schema.
+      # Includes all of the properties from +schemas+. Each argument must be the name of
+      # a schema defined by ClassMethods#api_schema or Definitions#schema.
       def all_of(*schemas)
         schemas.each { |schema| _meta_model.add_all_of({ schema: schema }) }
       end
 
-      # Specifies a sample matching the schema.
+      ##
+      # :method: conversion
+      # :args: method_or_proc
+      # Specifies the method or +Proc+ to convert values by.
+      #
+      #   conversion :upcase
+      #
+      #   conversion ->(value) { value.upcase }
+      #
+      # Raises an error if type is other than <code>"integer"</code>,
+      # <code>"number"</code> or <code>"string"</code>.
+
+      ##
+      # :method: default
+      # :args: value
+      # Specifies the default value.
+
+      ##
+      # :method: deprecated
+      # :args: arg
+      # Specifies whether or not the schema is deprecated.
+      #
+      #   deprecated true
+
+      ##
+      # :method: description
+      # :args: arg
+      # Specifies the description of the schema.
+
+      ##
+      # :method: enum
+      # :args: values
+      # Specifies the allowed values.
+      #
+      #   enum %w[foo bar]
+
+      ## :method: external_docs
+      ## :args: **keywords, &blocks
+      # Specifies the external documentation.
+      #
+      # See Meta::Schema::Base#external_docs for further information.
+
+      # Adds a sample matching the schema.
+      #
+      #   example 'foo'
       def example(example)
         _meta_model.add_example(example)
       end
 
-      # Overrides Kernel#format to handle +format+ as a keyword.
-      def format(format) # :nodoc:
+      ##
+      # :method: existence
+      # :args: level
+      # Specifies the level of existence.
+      #
+      #   existence :allow_nil
+      #
+      # See Meta::Schema::Base#existence for further information.
+
+      # Specifies the format of a string.
+      #
+      #   format 'date-time'
+      #
+      # Raises an Error if type is other than <code>"string"</code>.
+      #
+      # See Meta::Schema::String#format for further information.
+      def format(format)
         _keyword(:format, format)
       end
 
-      # Specifies the kind of items that can be contained in an array.
+      # Defines the kind of items that can be contained in an array.
       #
       #   items do
       #     property 'foo', type: 'string'
@@ -38,7 +96,57 @@ module Jsapi
         Schema.new(_meta_model.items, &block) if block
       end
 
-      # Specifies the model class to access nested object parameters by.
+      ##
+      # :method: max_items
+      # :args: value
+      # Specifies the maximum length of an array.
+      #
+      # Raises an Error if type is other than <code>"array"</code>.
+
+      ##
+      # :method: max_length
+      # :args: value
+      # Specifies the maximum length of a string.
+      #
+      # Raises an Error if type is other than <code>"string"</code>.
+
+      ##
+      # :method: maximum
+      # :args: value_or_keywords
+      # Specifies the maximum value of an integer or a number.
+      #
+      #   maximum 9
+      #
+      #   maximum value: 10, exclusive: true
+      #
+      # Raises an Error if type is other than <code>"integer"</code> or <code>"number"</code>.
+
+      ##
+      # :method: min_items
+      # :args: value
+      # Specifies the minimum length of an array.
+      #
+      # Raises an Error if type is other than <code>"array"</code>.
+
+      ##
+      # :method: min_length
+      # :args: min_length
+      # Specifies the minimum length of a string.
+      #
+      # Raises an Error if type is other than <code>"string"</code>.
+
+      ##
+      # :method: minimum
+      # :args: value_or_keywords
+      # Specifies the minimum value of an integer or a number.
+      #
+      #   minimum 1
+      #
+      #   minimum value: 0, exclusive: true
+      #
+      # Raises an Error if type is other than <code>"integer"</code> or <code>"number"</code>.
+
+      # Defines the model class to access nested object parameters by.
       #
       #   model Foo do
       #     def bar
@@ -46,9 +154,8 @@ module Jsapi
       #     end
       #   end
       #
-      # +klass+ can be any subclass of Model::Base. If block is given, an
-      # anonymous class is created that inherits either from +klass+ or
-      # Model::Base.
+      # +klass+ can be any subclass of Model::Base. If block is given, an anonymous class
+      # is created that inherits either from +klass+ or Model::Base.
       #
       # Raises an Error if type is other than <code>"object"</code>.
       def model(klass = nil, &block)
@@ -63,11 +170,25 @@ module Jsapi
         _meta_model.model = klass
       end
 
-      # Defines a property.
+      ##
+      # :method: multiple_of
+      # :args: value
+      # Specifies the value an integer or a number must be a multiple of.
+      #
+      # Raises an Error if type is other than <code>"integer"</code> or <code>"number"</code>.
+
+      ##
+      # :method: pattern
+      # :args: regex
+      # Specifies the regular expression a string must match.
+      #
+      # Raises an Error if type is other than <code>"string"</code>.
+
+      # Adds a property.
       #
       #   property 'foo', type: 'string'
       #
-      #   property 'foo' do
+      #   property 'foo', type: 'object' do
       #     property 'bar', type: 'string'
       #   end
       #
@@ -82,6 +203,11 @@ module Jsapi
           Schema.new(property_model, &block) if block
         end
       end
+
+      ##
+      # :method: title
+      # :args: arg
+      # Specifies the title of the schema.
     end
   end
 end

data/lib/jsapi/json/value.rb

@@ -29,8 +29,8 @@ module Jsapi
         false
       end
 
-      # Validates it against #schema. Returns +true+ if it is valid, +false+
-      # otherwise. Detected errors are added to +errors+.
+      # Validates it against #schema. Returns +true+ if it is valid, +false+ otherwise.
+      # Detected errors are added to +errors+.
       def validate(errors)
         unless schema.existence.reach?(self)
           errors.add(:base, :blank)

data/lib/jsapi/meta/attributes/type_caster.rb

@@ -34,8 +34,9 @@ module Jsapi
           @name = name
         end
 
-        # Casts +value+. Raises an InvalidArgumentError if the (casted)
-        # value is invalid.
+        # Casts +value+.
+        #
+        # Raises an InvalidArgumentError if the (casted) value is invalid.
         def cast(value)
           casted_value = @caster.call(value)
           return casted_value unless @values&.exclude?(casted_value)

data/lib/jsapi/meta/base.rb

@@ -6,8 +6,9 @@ module Jsapi
     class Base
       extend Attributes::ClassMethods
 
-      # Creates a new meta model. Raises an +ArgumentError+ if at least one
-      # keyword is not supported.
+      # Creates a new meta model.
+      #
+      # Raises an +ArgumentError+ if at least one keyword is not supported.
       def initialize(keywords = {})
         keywords.each do |key, value|
           if respond_to?(method = "#{key}=")

data/lib/jsapi/meta/base_reference.rb

@@ -2,14 +2,15 @@
 
 module Jsapi
   module Meta
+    # The base reference class.
     class BaseReference < Base
       ##
       # :attr: ref
       # The name of the referred object.
       attribute :ref, String
 
-      # Returns the name of the method to be invoked to look up the referred
-      # object in a Definitions instance.
+      # Returns the name of the method to be invoked to look up the referred object
+      # in a Definitions instance.
       def self.lookup_method_name
         @lookup_method_name ||=
           name.delete_suffix('::Reference').demodulize.underscore

data/lib/jsapi/meta/definitions.rb

@@ -168,7 +168,8 @@ module Jsapi
       private
 
       def default_operation_name
-        @default_operation_name ||= @owner.to_s.demodulize.delete_suffix('Controller').underscore
+        @default_operation_name ||=
+          @owner.to_s.demodulize.delete_suffix('Controller').underscore
       end
 
       def default_path

data/lib/jsapi/meta/example/model.rb

@@ -11,8 +11,7 @@ module Jsapi
 
         ##
         # :attr: external
-        # If true, +value+ is interpreted as a URI pointing to an external
-        # sample value.
+        # If true, +value+ is interpreted as a URI pointing to an external sample value.
         attribute :external, values: [true, false]
 
         ##

data/lib/jsapi/meta/example/reference.rb

@@ -12,4 +12,3 @@ module Jsapi
     end
   end
 end
-

data/lib/jsapi/meta/invalid_argument_error.rb

@@ -2,6 +2,7 @@
 
 module Jsapi
   module Meta
+    # Raised when an argument isn't contained in the list of valid values.
     class InvalidArgumentError < ArgumentError
       def initialize(name, value, values)
         super("#{name} must be one of #{values.inspect}, is #{value.inspect}")

data/lib/jsapi/meta/openapi/callback/model.rb

@@ -4,7 +4,7 @@ module Jsapi
   module Meta
     module OpenAPI
       module Callback
-        # Represents a callback object. Applies to \OpenAPI 3.x.
+        # Represents a callback object. Applies to \OpenAPI 3.0 and higher.
         class Model < Base
           ##
           # :attr: operations

data/lib/jsapi/meta/openapi/root.rb

@@ -7,7 +7,7 @@ module Jsapi
       class Root < Base
         ##
         # :attr: callbacks
-        # The reusable Callback objects. Applies to \OpenAPI 3.x.
+        # The reusable Callback objects. Applies to \OpenAPI 3.0 and higher.
         attribute :callbacks, { String => Callback }
 
         ##
@@ -41,7 +41,7 @@ module Jsapi
 
         ##
         # :attr: links
-        # The reusable Link objects. Applies to \OpenAPI 3.x.
+        # The reusable Link objects. Applies to \OpenAPI 3.0 and higher.
         attribute :links, { String => Link }
 
         ##
@@ -55,8 +55,7 @@ module Jsapi
 
         ##
         # :attr: schemes
-        # The array of transfer protocols supported by the API. Possible
-        # values are:
+        # The array of transfer protocols supported by the API. Possible values are:
         #
         # - <code>"http"</code>
         # - <code>"https"</code>
@@ -80,7 +79,7 @@ module Jsapi
 
         ##
         # :attr: servers
-        # The array of Server objects. Applies to \OpenAPI 3.x.
+        # The array of Server objects. Applies to \OpenAPI 3.0 and higher.
         attribute :servers, [Server]
 
         ##

data/lib/jsapi/meta/openapi/security_scheme/oauth2.rb

@@ -16,8 +16,7 @@ module Jsapi
           # - <code>"password"</code>
           #
           # Values are OAuthFlow objects.
-          attribute :oauth_flows,
-                    { String => OAuthFlow },
+          attribute :oauth_flows, { String => OAuthFlow },
                     keys: %w[authorization_code client_credentials implicit password]
 
           # Returns a hash representing the security scheme object.

data/lib/jsapi/meta/openapi/security_scheme/open_id_connect.rb

@@ -6,9 +6,8 @@ module Jsapi
       module SecurityScheme
         # Represents a security scheme based on OpenID Connect.
         #
-        # OpenID Connect was introduced with \OpenAPI 3.0. Thus, a security
-        # scheme of this class is skipped when generating an \OpenAPI 2.0
-        # document.
+        # OpenID Connect was introduced with \OpenAPI 3.0. Thus, a security scheme of
+        # this class is skipped when generating an \OpenAPI 2.0 document.
         class OpenIDConnect < Base
           ##
           # :attr: open_id_connect_url

data/lib/jsapi/meta/openapi/security_scheme.rb

@@ -30,11 +30,11 @@ module Jsapi
               APIKey.new(keywords)
             when 'basic' # OpenAPI 2.0
               HTTP.new(keywords.merge(scheme: 'basic'))
-            when 'http' # OpenAPI 3.x
+            when 'http' # OpenAPI 3.0 and higher
               HTTP.new(keywords)
             when 'oauth2'
               OAuth2.new(keywords)
-            when 'open_id_connect' # OpenAPI 3.x
+            when 'open_id_connect' # OpenAPI 3.0 and higher
               OpenIDConnect.new(keywords)
             else
               raise InvalidArgumentError.new(

data/lib/jsapi/meta/openapi/version.rb

@@ -4,6 +4,9 @@ module Jsapi
   module Meta
     module OpenAPI
       class Version
+        # Creates an \OpenAPI version from +version+.
+        #
+        # Raises an +ArgumentError+ if +version+ isn`t supported.
         def self.from(version)
           return version if version.is_a?(Version)
 

data/lib/jsapi/meta/operation.rb

@@ -5,13 +5,12 @@ module Jsapi
     class Operation < Base
       ##
       # :attr: callbacks
-      # The optional callbacks. Applies to \OpenAPI 3.x.
+      # The optional callbacks. Applies to \OpenAPI 3.0 and higher.
       attribute :callbacks, { String => OpenAPI::Callback }
 
       ##
       # :attr: consumed_mime_types
-      # The MIME types consumed by the operation.
-      # Applies to \OpenAPI 2.0 only.
+      # The MIME types consumed by the operation. Applies to \OpenAPI 2.0 only.
       attribute :consumed_mime_types, [String]
 
       alias :consumes :consumed_mime_types
@@ -25,12 +24,12 @@ module Jsapi
 
       ##
       # :attr: description
-      # The optional description of the operation.
+      # The description of the operation.
       attribute :description, String
 
       ##
       # :attr: external_docs
-      # The optional OpenAPI::ExternalDocumentation object.
+      # The OpenAPI::ExternalDocumentation object.
       attribute :external_docs, OpenAPI::ExternalDocumentation
 
       ##
@@ -46,14 +45,12 @@ module Jsapi
       # - <code>"put"</code>
       #
       # The default HTTP verb is <code>"get"</code>.
-      attribute :method,
-                values: %w[delete get head options patch post put],
-                default: 'get'
+      attribute :method, values: %w[delete get head options patch post put], default: 'get'
 
       ##
       # :attr: model
-      # The model class to access top-level parameters by. The default
-      # model class is Model::Base.
+      # The model class to access top-level parameters by. The default model class
+      # is Model::Base.
       attribute :model, Class, default: Model::Base
 
       ##
@@ -64,9 +61,7 @@ module Jsapi
       ##
       # :attr: parameters
       # The parameters of the operation.
-      attribute :parameters, { String => Parameter },
-                default: {},
-                writer: false
+      attribute :parameters, { String => Parameter }, default: {}, writer: false
 
       ##
       # :attr: path
@@ -75,8 +70,7 @@ module Jsapi
 
       ##
       # :attr: consumed_mime_types
-      # The MIME types produced by the operation.
-      # Applies to \OpenAPI 2.0 only.
+      # The MIME types produced by the operation. Applies to \OpenAPI 2.0 only.
       attribute :produced_mime_types, [String]
 
       alias :produces :produced_mime_types
@@ -85,20 +79,17 @@ module Jsapi
 
       ##
       # :attr: request_body
-      # The optional request body of the operation.
+      # The request body of the operation.
       attribute :request_body, RequestBody
 
       ##
       # :attr: responses
       # The responses of the operation.
-      attribute :responses, { String => Response },
-                default: {},
-                default_key: 'default'
+      attribute :responses, { String => Response }, default: {}, default_key: 'default'
 
       ##
       # :attr: schemes
-      # The transfer protocols supported by the operation. Possible
-      # values are:
+      # The transfer protocols supported by the operation. Possible values are:
       #
       # - <code>"http"</code>
       # - <code>"https"</code>
@@ -117,17 +108,17 @@ module Jsapi
 
       ##
       # :attr: servers
-      # The OpenAPI::Server objects. Applies to \OpenAPI 3.x.
+      # The OpenAPI::Server objects. Applies to \OpenAPI 3.0 and higher.
       attribute :servers, [OpenAPI::Server]
 
       ##
       # :attr: summary
-      # The optional summary of the operation.
+      # The short summary of the operation.
       attribute :summary, String
 
       ##
       # :attr: tags
-      # The tags used to group operations in an \OpenAPI document.
+      # The tags. Tags are used to group operations in an \OpenAPI document.
       attribute :tags, [String]
 
       def initialize(name = nil, keywords = {})

data/lib/jsapi/meta/parameter/model.rb

@@ -11,12 +11,12 @@ module Jsapi
 
         ##
         # :attr: description
-        # The optional description of the parameter.
+        # The description of the parameter.
         attribute :description, String
 
         ##
         # :attr_reader: examples
-        # The optional examples.
+        # The examples.
         attribute :examples, { String => Example }, default_key: 'default'
 
         ##

data/lib/jsapi/meta/parameter/reference.rb

@@ -4,10 +4,9 @@ module Jsapi
   module Meta
     module Parameter
       class Reference < BaseReference
-        # Returns an array of hashes. Each element represents an \OpenAPI
-        # parameter object if the type of the referred parameter is
-        # <code>"object"</code>. Otherwise the array contains a single
-        # hash representing the \OpenAPI reference object.
+        # Returns an array of hashes. Each element represents an \OpenAPI parameter object
+        # if the type of the referred parameter is <code>"object"</code>. Otherwise the
+        # array contains a single hash representing the \OpenAPI reference object.
         #
         # Raises a ReferenceError if the reference could not be resolved.
         def to_openapi(version, definitions)

data/lib/jsapi/meta/property.rb

@@ -19,8 +19,7 @@ module Jsapi
 
       ##
       # :attr: source
-      # The alternative method to read a property value when serializing
-      # an object.
+      # The alternative method to read a property value when serializing an object.
       attribute :source, Symbol
 
       ##
@@ -42,8 +41,8 @@ module Jsapi
         @schema = Schema.new(keywords)
       end
 
-      # Returns true if the level of existence is greater than or equal to
-      # +ALLOW_NIL+, false otherwise.
+      # Returns true if the level of existence is greater than or equal to +ALLOW_NIL+,
+      # false otherwise.
       def required?
         schema.existence >= Existence::ALLOW_NIL
       end

data/lib/jsapi/meta/request_body/model.rb

@@ -16,7 +16,7 @@ module Jsapi
 
         ##
         # :attr_reader: schema
-        # The Schema of the parameter.
+        # The Schema of the request body.
         attribute :schema, writer: false
 
         delegate_missing_to :schema

data/lib/jsapi/meta/rescue_handler.rb

@@ -2,9 +2,15 @@
 
 module Jsapi
   module Meta
+    # Maps a +StandardError+ class to a response status.
     class RescueHandler
+      # The response status.
       attr_reader :status
 
+      # Creates a new rescue handler to map +klass+ to +status+. The default response status
+      # is <code>"default"</code>.
+      #
+      # Raises an +ArgumentError+ if +klass+ isn't a +StandardError+ class.
       def initialize(klass, status: nil)
         unless klass.is_a?(Class) && klass.ancestors.include?(StandardError)
           raise ArgumentError, "#{klass.inspect} must be a standard error class"
@@ -18,6 +24,7 @@ module Jsapi
         "#<#{self.class.name} class: #{@klass}, status: #{@status.inspect}>"
       end
 
+      # Returns true if +exception+ is an instance of the class to be mapped, false otherwise.
       def match?(exception)
         exception.is_a?(@klass)
       end

data/lib/jsapi/meta/response/model.rb

@@ -26,7 +26,7 @@ module Jsapi
 
         ##
         # :attr_reader: schema
-        # The Schema of the parameter.
+        # The Schema of the response.
         attribute :schema, writer: false
 
         delegate_missing_to :schema

data/lib/jsapi/meta/schema/base.rb

@@ -12,7 +12,7 @@ module Jsapi
 
         ##
         # :attr: default
-        # The optional default value.
+        # The default value.
         attribute :default
 
         ##
@@ -22,7 +22,7 @@ module Jsapi
 
         ##
         # :attr: description
-        # The optional description of the schema.
+        # The description of the schema.
         attribute :description, ::String
 
         ##
@@ -32,23 +32,22 @@ module Jsapi
 
         ##
         # :attr: examples
-        # The optional examples.
+        # The samples matching the schema.
         attribute :examples, [::Object]
 
         ##
         # :attr: external_docs
-        # The optional OpenAPI::ExternalDocumentation object.
+        # The OpenAPI::ExternalDocumentation object.
         attribute :external_docs, OpenAPI::ExternalDocumentation
 
         ##
         # :attr: existence
-        # The level of Existence. The default level of existence
-        # is +ALLOW_OMITTED+.
+        # The level of Existence. The default level of existence is +ALLOW_OMITTED+.
         attribute :existence, Existence, default: Existence::ALLOW_OMITTED
 
         ##
         # :attr: title
-        # The optional title of the schema.
+        # The title of the schema.
         attribute :title, String
 
         ##
@@ -73,8 +72,7 @@ module Jsapi
           @enum = value
         end
 
-        # Returns true if and only if values can be +null+ as specified
-        # by \JSON \Schema.
+        # Returns true if and only if values can be +null+ as specified by \JSON \Schema.
         def nullable?
           existence <= Existence::ALLOW_NIL
         end

data/lib/jsapi/meta/schema/reference.rb

@@ -9,8 +9,7 @@ module Jsapi
 
         ##
         # :attr: existence
-        # The level of Existence. The default level of existence
-        # is +ALLOW_OMITTED+.
+        # The level of Existence. The default level of existence is +ALLOW_OMITTED+.
         attribute :existence, Existence, default: Existence::ALLOW_OMITTED
 
         def resolve(definitions) # :nodoc:

data/lib/jsapi/meta/schema/string.rb

@@ -8,7 +8,7 @@ module Jsapi
 
         ##
         # :attr: format
-        # The optional format of a string. Possible values are:
+        # The format of a string. Possible values are:
         #
         # - <code>"date"</code>
         # - <code>"date-time"</code>