jsapi 0.8.0 → 0.9.1

data/lib/jsapi/dsl/examples.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module DSL
+    module Examples
+      # Specifies an example.
+      #
+      #   example 'foo', value: 'bar'
+      #
+      #   example 'foo'
+      #
+      # The default name is <code>'default'</code>.
+      def example(name_or_value = nil, **keywords, &block)
+        define('example', name_or_value&.inspect) do
+          if keywords.any? || block
+            # example 'foo', value: 'bar', ...
+            name = name_or_value
+          else
+            # example 'foo'
+            name = nil
+            keywords = { value: name_or_value }
+          end
+
+          example = @meta_model.add_example(name, keywords)
+          Base.new(example, &block) if block
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/dsl/operation.rb

@@ -2,9 +2,34 @@
 
 module Jsapi
   module DSL
-    # Used to specify details of an operation.
-    class Operation < Node
-      include OpenAPI::Callbacks
+    # Used to define an API operation.
+    class Operation < Base
+
+      # Specifies a callback.
+      #
+      #   callback 'foo' do
+      #     operation '{$request.query.bar}'
+      #   end
+      #
+      # Refers a resuable callback if the `:ref` keyword is specified.
+      #
+      #   callback ref: 'foo'
+      #
+      # Refers the reusable callback object with the same name if neither any
+      # keywords nor a block is specified.
+      #
+      #   callback 'foo'
+      #
+      # See Meta::Operation#callbacks for further information.
+      def callback(name = nil, **keywords, &block)
+        define('callback', name&.inspect) do
+          name = keywords[:ref] if name.nil?
+          keywords = { ref: name } unless keywords.any? || block
+
+          callback_model = @meta_model.add_callback(name, keywords)
+          Callback.new(callback_model, &block) if block
+        end
+      end
 
       ##
       # :method: deprecated
@@ -24,7 +49,7 @@ module Jsapi
       #
       # See Meta::Operation#method for further information.
       def method(arg)
-        _keyword(:method, arg)
+        keyword(:method, arg)
       end
 
       # Defines the model class to access top-level parameters by.
@@ -35,41 +60,41 @@ 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.
       def model(klass = nil, &block)
         if block
           klass = Class.new(klass || Model::Base)
           klass.class_eval(&block)
         end
-        _meta_model.model = klass
+        @meta_model.model = klass
       end
 
-      # Adds a parameter or a reference to a reusable parameter.
+      # Specifies a parameter
       #
-      #   # define a parameter
       #   parameter 'foo', type: 'string'
       #
-      #   # define a nested parameter
       #   parameter 'foo', type: 'object' do
       #     property 'bar', type: 'string'
       #   end
       #
-      #   # refer a reusable parameter
+      # Refers a resuable parameter if the `:ref` keyword is specified.
+      #
       #   parameter ref: 'foo'
       #
-      # Refers the reusable parameter with the same name if neither any keywords nor a
-      # block is specified.
+      # Refers the reusable parameter with the same name if neither any keywords
+      # nor a block is specified.
       #
       #   parameter 'foo'
       #
+      # See Meta::Operation#parameters for further information.
       def parameter(name = nil, **keywords, &block)
-        _define('parameter', name&.inspect) do
+        define('parameter', name&.inspect) do
           name = keywords[:ref] if name.nil?
           keywords = { ref: name } unless keywords.any? || block
 
-          parameter_model = _meta_model.add_parameter(name, keywords)
-          _eval(parameter_model, Parameter, &block)
+          parameter_model = @meta_model.add_parameter(name, keywords)
+          Parameter.new(parameter_model, &block) if block
         end
       end
 
@@ -78,14 +103,14 @@ module Jsapi
       # :args: arg
       # Specifies the relative path of the operation.
 
-      # Defines the request body or refers a reusable request body.
+      # Specifies the request body.
       #
-      #   # define a request body
       #   request_body type: 'object' do
       #     property 'foo', type: 'string'
       #   end
       #
-      #   # refer a reusable request body
+      # Refers a resuable request body if the `:ref` keyword is specified.
+      #
       #   request_body ref: 'foo'
       #
       # Refers the reusable request body with the same name if neither any
@@ -93,34 +118,37 @@ module Jsapi
       #
       #   request_body 'foo'
       #
+      # See Meta::Operation#request_body for further information.
       def request_body(**keywords, &block)
-        _define('request body') do
-          _meta_model.request_body = keywords
-          _eval(_meta_model.request_body, RequestBody, &block)
+        define('request body') do
+          @meta_model.request_body = keywords
+          RequestBody.new(@meta_model.request_body, &block) if block
         end
       end
 
-      # Adds a response or a reference to a reusable response.
+      # Specifies a response.
       #
-      #   # define a response
       #   response 200, type: 'object' do
       #     property 'foo', type: 'string'
       #   end
       #
-      #   # refer a reusable response
-      #   response 200, ref: 'foo'
-      #
       # The default status is <code>"default"</code>.
       #
+      # Refers a resuable response if the `:ref` keyword is specified.
+      #
+      #   response 200, ref: 'foo'
+      #
       # Refers the reusable response with the same name if neither any keywords
       # nor a block is specified.
       #
       #   response 'foo'
       #
       # Raises an Error if name is specified together with keywords or a block.
+      #
+      # See Meta::Operation#responses for further information.
       def response(status_or_name = nil, name = nil, **keywords, &block)
-        _define('response', status_or_name&.inspect) do
-          raise Error, 'name cannot be specified together with keywords ' \
+        define('response', status_or_name&.inspect) do
+          raise Error, "name can't be specified together with keywords " \
                        'or a block' if name && (keywords.any? || block)
 
           if keywords.any? || block
@@ -129,8 +157,8 @@ module Jsapi
             status = status_or_name if name
             keywords = { ref: name || status_or_name }
           end
-          response_model = _meta_model.add_response(status, keywords)
-          _eval(response_model, Response, &block)
+          response_model = @meta_model.add_response(status, keywords)
+          Response.new(response_model, &block) if block
         end
       end
 
@@ -149,7 +177,7 @@ module Jsapi
       ##
       # :method: tags
       # :args: names
-      # Specifies all of the tags at once.
+      # Specifies all tags at once.
       #
       #   tags %w[foo bar]
     end

data/lib/jsapi/dsl/parameter.rb

@@ -2,9 +2,9 @@
 
 module Jsapi
   module DSL
-    # Used to specify details of a parameter.
+    # Used to define a parameter.
     class Parameter < Schema
-      include OpenAPI::Examples
+      include Examples
 
       ##
       # :method: deprecated

data/lib/jsapi/dsl/request_body.rb

@@ -2,9 +2,9 @@
 
 module Jsapi
   module DSL
-    # Used to specify details of a request body.
+    # Used to define a request body.
     class RequestBody < Schema
-      include OpenAPI::Examples
+      include Examples
 
       ##
       # :method: deprecated

data/lib/jsapi/dsl/response.rb

@@ -2,9 +2,9 @@
 
 module Jsapi
   module DSL
-    # Used to specify details of a response.
+    # Used to define a response.
     class Response < Schema
-      include OpenAPI::Examples
+      include Examples
 
       ##
       # :method: deprecated
@@ -18,33 +18,57 @@ module Jsapi
       # :args: arg
       # Specifies the description of the response.
 
-      # Defines a link or refers a reusable link object.
+      # Specifies an HTTP header of the response.
+      #
+      #   header 'X-Foo', type: 'string'
+      #
+      # Refers a resuable header if the `:ref` keyword is specified.
+      #
+      #   header ref: 'x_foo'
+      #
+      # Refers the reusable header with the same name if neither any keywords
+      # nor a block is specified.
+      #
+      #   header 'x_foo'
+      #
+      # See Meta::Response::Model#headers for further information.
+      def header(name = nil, **keywords, &block)
+        define('header', name&.inspect) do
+          name = keywords[:ref] if name.nil?
+          keywords = { ref: name } unless keywords.any? || block
+
+          header_model = @meta_model.add_header(name, keywords)
+          Base.new(header_model, &block) if block
+        end
+      end
+
+      # Specifies a link.
       #
-      #   # define a link
       #   link 'foo', operation_id: 'bar'
       #
-      #   # refer a reusable link
+      # Refers a reusable link if the `:ref` keyword is specified.
+      #
       #   link ref: 'foo'
       #
-      # Refers the reusable link object with the same name if neither any
-      # keywords nor a block is specified.
+      # Refers the reusable link with the same name if neither any keywords
+      # nor a block is specified.
       #
       #   link 'foo'
       #
       def link(name = nil, **keywords, &block)
-        _define('link', name&.inspect) do
+        define('link', name&.inspect) do
           name = keywords[:ref] if name.nil?
           keywords = { ref: name } unless keywords.any? || block
 
-          link_model = _meta_model.add_link(name, keywords)
-          Node.new(link_model, &block) if block
+          link_model = @meta_model.add_link(name, keywords)
+          Base.new(link_model, &block) if block
         end
       end
 
       ##
       # :method: locale
       # :args: arg
-      # Specifies the locale to be used when rendering a response.
+      # Specifies the locale to be used when producing a response.
       #
       #   locale :en
     end

data/lib/jsapi/dsl/schema.rb

@@ -2,13 +2,13 @@
 
 module Jsapi
   module DSL
-    # Used to specify details of a schema.
-    class Schema < Node
+    # Used to define a schema.
+    class Schema < Base
 
       # 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({ ref: schema }) }
+        schemas.each { |schema| @meta_model.add_all_of({ ref: schema }) }
       end
 
       ##
@@ -57,7 +57,7 @@ module Jsapi
       #
       #   example 'foo'
       def example(example)
-        _meta_model.add_example(example)
+        @meta_model.add_example(example)
       end
 
       ##
@@ -77,7 +77,7 @@ module Jsapi
       #
       # See Meta::Schema::String#format for further information.
       def format(format)
-        _keyword(:format, format)
+        keyword(:format, format)
       end
 
       # Defines the kind of items that can be contained in an array.
@@ -88,12 +88,12 @@ module Jsapi
       #
       # Raises an Error if type is other than <code>"array"</code>.
       def items(**keywords, &block)
-        unless _meta_model.respond_to?(:items=)
-          raise Error, "items isn't supported for '#{_meta_model.type}'"
+        unless @meta_model.respond_to?(:items=)
+          raise Error, "items isn't supported for '#{@meta_model.type}'"
         end
 
-        _meta_model.items = keywords
-        Schema.new(_meta_model.items, &block) if block
+        @meta_model.items = keywords
+        Schema.new(@meta_model.items, &block) if block
       end
 
       ##
@@ -159,15 +159,15 @@ module Jsapi
       #
       # Raises an Error if type is other than <code>"object"</code>.
       def model(klass = nil, &block)
-        unless _meta_model.respond_to?(:model=)
-          raise Error, "model isn't supported for '#{_meta_model.type}'"
+        unless @meta_model.respond_to?(:model=)
+          raise Error, "model isn't supported for '#{@meta_model.type}'"
         end
 
         if block
           klass = Class.new(klass || Model::Base)
           klass.class_eval(&block)
         end
-        _meta_model.model = klass
+        @meta_model.model = klass
       end
 
       ##
@@ -194,12 +194,12 @@ module Jsapi
       #
       # Raises an Error if type is other than <code>"object"</code>.
       def property(name, **keywords, &block)
-        _define('property', name.inspect) do
-          unless _meta_model.respond_to?(:add_property)
-            raise Error, "property isn't supported for '#{_meta_model.type}'"
+        define('property', name.inspect) do
+          unless @meta_model.respond_to?(:add_property)
+            raise Error, "property isn't supported for '#{@meta_model.type}'"
           end
 
-          property_model = _meta_model.add_property(name, keywords)
+          property_model = @meta_model.add_property(name, keywords)
           Schema.new(property_model, &block) if block
         end
       end

data/lib/jsapi/dsl.rb

@@ -1,19 +1,19 @@
 # frozen_string_literal: true
 
 require_relative 'dsl/error'
-require_relative 'dsl/node'
-require_relative 'dsl/openapi'
+require_relative 'dsl/base'
+require_relative 'dsl/examples'
 require_relative 'dsl/schema'
 require_relative 'dsl/parameter'
 require_relative 'dsl/request_body'
 require_relative 'dsl/response'
+require_relative 'dsl/callback'
 require_relative 'dsl/operation'
 require_relative 'dsl/definitions'
 require_relative 'dsl/class_methods'
 
 module Jsapi
-  # Provides class methods to define top-level API components.
-  # See ClassMethods for details.
+  # The \DSL to define API components.
   module DSL
     def self.included(base) # :nodoc:
       base.extend(ClassMethods)

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

@@ -4,9 +4,11 @@ module Jsapi
   module Meta
     module Base
       module Attributes
+        DEFAULT_ARRAY = [].freeze
+        DEFAULT_HASH = {}.freeze
+
         # Defines an attribute.
         def attribute(name, type = Object,
-                      add_method: nil,
                       default: nil,
                       default_key: nil,
                       keys: nil,
@@ -17,26 +19,20 @@ module Jsapi
 
           instance_variable_name = "@#{name}"
 
-          # Attribute reader
-          define_method(name) do
-            value = instance_variable_get(instance_variable_name)
-            value.nil? ? default : value
-          end
-
           case type
           when Array
+            # General default
+            default ||= DEFAULT_ARRAY
+
             unless read_only
               singular_name = name.to_s.singularize
-              add_method = "add_#{singular_name}" if add_method.nil?
+              add_method = "add_#{singular_name}"
 
               type_caster = TypeCaster.new(type.first, values: values, name: singular_name)
 
               # Attribute writer
               define_method("#{name}=") do |argument|
-                if argument.nil?
-                  instance_variable_set(instance_variable_name, nil)
-                else
-                  instance_variable_set(instance_variable_name, [])
+                instance_variable_set(instance_variable_name, []).tap do
                   Array.wrap(argument).each { |element| send(add_method, element) }
                 end
               end
@@ -59,24 +55,24 @@ module Jsapi
             key_type, value_type = type.first
             key_type_caster = TypeCaster.new(key_type, values: keys, name: 'key')
 
+            # General default
+            default ||= DEFAULT_HASH
+
             # Lookup method
             define_method(singular_name) do |key = nil|
               key = default_key if key.to_s.empty?
-              send(name)&.[](key_type_caster.cast(key))
+              send(name)[key_type_caster.cast(key)]
             end
 
             unless read_only
-              add_method = "add_#{singular_name}" if add_method.nil?
+              add_method = "add_#{singular_name}"
 
               value_type_caster = TypeCaster.new(value_type, values: values)
 
               # Attribute writer
               define_method("#{name}=") do |argument|
-                if argument.nil?
-                  instance_variable_set(instance_variable_name, nil)
-                else
-                  instance_variable_set(instance_variable_name, {})
-                  argument.each { |key, value| send(add_method, key, value) }
+                instance_variable_set(instance_variable_name, {}).tap do
+                  Hash(argument).each { |key, value| send(add_method, key, value) }
                 end
               end
 
@@ -123,6 +119,12 @@ module Jsapi
               end
             end
           end
+
+          # Attribute reader
+          define_method(name) do
+            value = instance_variable_get(instance_variable_name)
+            value.nil? ? default : value
+          end
         end
 
         def attribute_names

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

@@ -11,13 +11,7 @@ module Jsapi
         #
         # Raises an +ArgumentError+ if at least one keyword is not supported.
         def initialize(keywords = {})
-          keywords.each do |key, value|
-            if respond_to?(method = "#{key}=")
-              public_send(method, value)
-            else
-              raise ArgumentError, "unsupported keyword: #{key}"
-            end
-          end
+          merge!(keywords)
         end
 
         def inspect(*attributes) # :nodoc:
@@ -30,6 +24,20 @@ module Jsapi
           }>"
         end
 
+        # Merges +keywords+ into the model.
+        #
+        # Raises an +ArgumentError+ if at least one keyword is not supported.
+        def merge!(keywords = {})
+          keywords.each do |key, value|
+            if respond_to?(method = "#{key}=")
+              public_send(method, value)
+            else
+              raise ArgumentError, "unsupported keyword: #{key}"
+            end
+          end
+          self
+        end
+
         # Returns false.
         def reference?
           false

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    class Operation < Base::Model; end
+
+    module Callback
+      # Specifies a callback object. Applies to \OpenAPI 3.0 and higher.
+      class Model < Base::Model
+        ##
+        # :attr: operations
+        attribute :operations, { String => Operation }
+
+        undef add_operation
+
+        # Adds a callback operation.
+        #
+        # Raises an +ArgumentError+ if +expression+ is blank.
+        def add_operation(expression, keywords = {})
+          raise ArgumentError, "expression can't be blank" if expression.blank?
+
+          (@operations ||= {})[expression.to_s] = Operation.new(nil, keywords)
+        end
+
+        # Returns a hash representing the \OpenAPI callback object.
+        def to_openapi(version, definitions)
+          operations.transform_values do |operation|
+            { operation.method => operation.to_openapi(version, definitions) }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Callback
+      class Reference < Base::Reference
+        # Returns a hash representing the \OpenAPI reference object.
+        def to_openapi(*)
+          { '$ref': "#/components/callbacks/#{ref}" }
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/callback.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'callback/model'
+require_relative 'callback/reference'
+
+module Jsapi
+  module Meta
+    module Callback
+      class << self
+        # Creates a Model or Reference.
+        def new(keywords = {})
+          return Reference.new(keywords) if keywords.key?(:ref)
+
+          Model.new(keywords)
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/contact.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    # Specifies a contact object.
+    class Contact < Base::Model
+      include OpenAPI::Extensions
+
+      ##
+      # :attr: email
+      # The email address of the contact.
+      attribute :email, String
+
+      ##
+      # :attr: name
+      # The name of the contact.
+      attribute :name, String
+
+      ##
+      # :attr: url
+      # The URL of the contact.
+      attribute :url, String
+
+      # Returns a hash representing the \OpenAPI contact object.
+      def to_openapi(*)
+        with_openapi_extensions(name: name, url: url, email: email)
+      end
+    end
+  end
+end

data/lib/jsapi/meta/defaults.rb

@@ -5,12 +5,12 @@ module Jsapi
     # Holds the default values for a particular Schema type.
     class Defaults < Base::Model
       ##
-      # :attr: read
+      # :attr: within_requests
       # The default value of parameters and properties when reading requests.
       attribute :within_requests
 
       ##
-      # :attr: write
+      # :attr: within_responses
       # The default value of properties when writing responses.
       attribute :within_responses