jsapi 0.1.1 → 0.2.0

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 }) }
+        schemas.each { |schema| _meta_model.add_all_of({ ref: 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/array.rb

@@ -11,7 +11,7 @@ module Jsapi
         end
       end
 
-      # Returns +true+ if it contains no elements, +false+ otherwise.
+      # Returns true if it contains no elements, false otherwise.
       def empty?
         @elements.empty?
       end
@@ -20,8 +20,7 @@ module Jsapi
         "#<#{self.class.name} [#{@elements.map(&:inspect).join(', ')}]>"
       end
 
-      # See Value#validate.
-      def validate(errors)
+      def validate(errors) # :nodoc:
         return false unless super
 
         @elements.map { |element| element.validate(errors) }.all?

data/lib/jsapi/json/null.rb

@@ -5,7 +5,7 @@ module Jsapi
     # Represents +null+.
     class Null < Value
 
-      # Returns allways +true+.
+      # Returns true.
       def empty?
         true
       end
@@ -14,7 +14,7 @@ module Jsapi
         "#<#{self.class}>"
       end
 
-      # Returns allways +true+.
+      # Returns true.
       def null?
         true
       end

data/lib/jsapi/json/object.rb

@@ -25,7 +25,7 @@ module Jsapi
         super(schema)
       end
 
-      # Returns +true+ if all attributes are empty, +false+ otherwise.
+      # Returns true if all attributes are empty, false otherwise.
       def empty?
         @raw_attributes.values.all?(&:empty?)
       end

data/lib/jsapi/json/string.rb

@@ -8,22 +8,36 @@ module Jsapi
 
       def initialize(value, schema)
         super(schema)
-        @value = schema.convert(
-          case schema.format
-          when 'date'
-            value.to_date
-          when 'date-time'
-            value.to_datetime
-          else
-            value.to_s
+
+        @value =
+          begin
+            case schema.format
+            when 'date'
+              value.to_date
+            when 'date-time'
+              value.to_datetime
+            when 'duration'
+              ActiveSupport::Duration.parse(value)
+            else
+              value.to_s
+            end
+          rescue StandardError => e
+            @error = e
+            value
           end
-        )
+        @value = schema.convert(@value) unless defined? @error
       end
 
-      # See Value#empty?.
-      def empty?
+      def empty? # :nodoc:
         value.blank?
       end
+
+      def validate(errors) # :nodoc:
+        return super unless defined? @error
+
+        errors.add(:base, :invalid)
+        false
+      end
     end
   end
 end

data/lib/jsapi/json/value.rb

@@ -14,7 +14,7 @@ module Jsapi
       end
 
       # Used by #validate to test whether or not it is empty.
-      # Returns +false+ by default.
+      # Returns false by default.
       def empty?
         false
       end
@@ -23,14 +23,14 @@ module Jsapi
         "#<#{self.class} #{value.inspect}>"
       end
 
-      # Used by #validate to test whether or not it is +null+.
-      # Returns +false+ by default.
+      # Used by #validate to test whether or not it is null.
+      # Returns false by default.
       def null?
         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]
 
         ##
@@ -97,12 +96,13 @@ module Jsapi
             end
 
           if version.major == 2
+            uri = servers&.first&.then { |server| URI(server.url) }
             {
               swagger: '2.0',
               info: info&.to_openapi,
-              host: host,
-              basePath: base_path,
-              schemes: schemes,
+              host: host || uri&.hostname,
+              basePath: base_path || uri&.path,
+              schemes: schemes || uri&.scheme&.then { |scheme| [scheme] },
               consumes: consumed_mime_types,
               produces: produced_mime_types,
               securityDefinitions: security_schemes,

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'
 
         ##
@@ -47,12 +47,14 @@ module Jsapi
         def initialize(name, keywords = {})
           raise ArgumentError, "parameter name can't be blank" if name.blank?
 
+          @name = name.to_s
+
           keywords = keywords.dup
           super(keywords.extract!(:deprecated, :description, :examples, :in))
 
           add_example(value: keywords.delete(:example)) if keywords.key?(:example)
+          keywords[:ref] = keywords.delete(:schema) if keywords.key?(:schema)
 
-          @name = name.to_s
           @schema = Schema.new(keywords)
         end