jsapi 1.4 → 2.0

data/lib/jsapi/controller.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
-require_relative 'controller/parameters_invalid'
 require_relative 'controller/error'
+require_relative 'controller/authentication'
 require_relative 'controller/parameters'
 require_relative 'controller/response'
 require_relative 'controller/methods'
+require_relative 'controller/actions'
 require_relative 'controller/base'
 
 module Jsapi

data/lib/jsapi/dsl/base.rb

@@ -2,6 +2,37 @@
 
 module Jsapi
   module DSL
+    # Raised when an error occurred while defining an API component.
+    class Error < StandardError
+
+      # Creates a new error. +origin+ is the innermost position at where the error occurred.
+      def initialize(error_or_message, origin = nil)
+        @path = Array(origin)
+        super(
+          if error_or_message.respond_to?(:message)
+            error_or_message.message
+          else
+            error_or_message
+          end
+        )
+      end
+
+      # Overrides <code>StandardError#message</code> to append the whole path of the position
+      # at where the error occurred, for example: <code>{message} (at foo / bar)</code>.
+      def message
+        message = super
+        return message if @path.empty?
+
+        "#{message} (at #{@path.join(' / ')})"
+      end
+
+      # Prepends +origin+ to the path at where the error occurred.
+      def prepend_origin(origin)
+        @path.prepend(origin) if origin.present?
+        self
+      end
+    end
+
     class Base
       def initialize(meta_model, pathname = nil, parent: nil, &block)
         @meta_model = meta_model
@@ -48,8 +79,8 @@ module Jsapi
         self.class.new(@meta_model, pathname, parent: self)
       end
 
-      def respond_to_missing?(*args) # :nodoc:
-        keyword?(args.first)
+      def respond_to_missing?(param1, *) # :nodoc:
+        keyword?(param1)
       end
 
       protected
@@ -59,7 +90,8 @@ module Jsapi
       private
 
       def define(*args, &block)
-        block.call
+        result = block.call
+        result.freeze_attributes if result.respond_to?(:freeze_attributes)
       rescue Error => e
         raise e.prepend_origin(args.compact.join(' '))
       rescue StandardError => e
@@ -77,8 +109,9 @@ module Jsapi
         raise "unsupported keyword: #{name}" unless method
 
         define(name) do
-          result = @meta_model.public_send(method, *params)
-          Base.new(result, &block) if block
+          @meta_model.public_send(method, *params).tap do |result|
+            Base.new(result, &block) if block
+          end
         end
       end
 

data/lib/jsapi/dsl/class_methods.rb

@@ -154,8 +154,8 @@ module Jsapi
       #     operation 'bar'
       #   end
       #
-      def api_path(name, &block)
-        api_definitions { path(name, &block) }
+      def api_path(name, **keywords, &block)
+        api_definitions { path(name, **keywords, &block) }
       end
 
       # Defines a reusable request body.

data/lib/jsapi/dsl/definitions.rb

@@ -22,8 +22,9 @@ module Jsapi
       # See Meta::Definitions#callbacks for further information.
       def callback(name, **keywords, &block)
         define('callback', name.inspect) do
-          callback = @meta_model.add_callback(name, keywords)
-          Callback.new(callback, &block) if block
+          @meta_model.add_callback(name, keywords).tap do |callback|
+            Base.new(callback, &block) if block
+          end
         end
       end
 
@@ -34,8 +35,9 @@ module Jsapi
       # See Meta::Definitions#defaults for further information.
       def default(type, **keywords, &block)
         define('default', type.inspect) do
-          default = @meta_model.add_default(type, keywords)
-          Base.new(default, &block) if block
+          @meta_model.add_default(type, keywords).tap do |default|
+            Base.new(default, &block) if block
+          end
         end
       end
 
@@ -46,8 +48,9 @@ module Jsapi
       # See Meta::Definitions#examples for further information.
       def example(name, **keywords, &block)
         define('example', name.inspect) do
-          example = @meta_model.add_example(name, keywords)
-          Base.new(example, &block) if block
+          @meta_model.add_example(name, keywords).tap do |example|
+            Base.new(example, &block) if block
+          end
         end
       end
 
@@ -74,8 +77,9 @@ module Jsapi
       # See Meta::Definitions#headers for further information.
       def header(name, **keywords, &block)
         define('header', name.inspect) do
-          header = @meta_model.add_header(name, keywords)
-          Base.new(header, &block) if block
+          @meta_model.add_header(name, keywords).tap do |header|
+            Base.new(header, &block) if block
+          end
         end
       end
 
@@ -106,8 +110,9 @@ module Jsapi
       # See Meta::Definitions#links for further information.
       def link(name, **keywords, &block)
         define('link', name.inspect) do
-          link = @meta_model.add_link(name, keywords)
-          Base.new(link, &block) if block
+          @meta_model.add_link(name, keywords).tap do |link|
+            Base.new(link, &block) if block
+          end
         end
       end
 
@@ -138,8 +143,9 @@ module Jsapi
       # See Meta::Definitions#operations for further information.
       def operation(name = nil, **keywords, &block)
         define('operation', name&.inspect) do
-          operation_model = @meta_model.add_operation(name, keywords)
-          Operation.new(operation_model, &block) if block
+          @meta_model.add_operation(name, keywords).tap do |operation_model|
+            Operation.new(operation_model, &block) if block
+          end
         end
       end
 
@@ -150,8 +156,9 @@ module Jsapi
       # See Meta::Definitions#parameters for further information.
       def parameter(name, **keywords, &block)
         define('parameter', name.inspect) do
-          parameter_model = @meta_model.add_parameter(name, keywords)
-          Parameter.new(parameter_model, &block) if block
+          @meta_model.add_parameter(name, keywords).tap do |parameter_model|
+            Parameter.new(parameter_model, &block) if block
+          end
         end
       end
 
@@ -162,10 +169,11 @@ module Jsapi
       #     operation 'bar'
       #   end
       #
-      def path(name = nil, &block)
+      def path(name = nil, **keywords, &block)
         define('path', name&.inspect) do
-          path_model = @meta_model.add_path(name)
-          Path.new(path_model, &block) if block
+          @meta_model.add_path(name, keywords).tap do |path_model|
+            Path.new(path_model, &block) if block
+          end
         end
       end
 
@@ -176,19 +184,22 @@ module Jsapi
       # See Meta::Definitions#request_bodies for further information.
       def request_body(name, **keywords, &block)
         define('request_body', name.inspect) do
-          request_body_model = @meta_model.add_request_body(name, keywords)
-          RequestBody.new(request_body_model, &block) if block
+          @meta_model.add_request_body(name, keywords).tap do |request_body_model|
+            RequestBody.new(request_body_model, &block) if block
+          end
         end
       end
 
-      # Specifies the HTTP status code of an error response rendered when an exception of
+      # Specifies the status code of a response to be produced when an error of
       # any of +klasses+ has been raised.
       #
       #   rescue_from Jsapi::Controller::ParametersInvalid, with: 400
       #
       def rescue_from(*klasses, with: nil)
         klasses.each do |klass|
-          @meta_model.add_rescue_handler({ error_class: klass, status: with })
+          @meta_model.add_rescue_handler(
+            { error_class: klass, status_code: with }
+          )
         end
       end
 
@@ -201,8 +212,9 @@ module Jsapi
       # See Meta::Definitions#responses for further information.
       def response(name, **keywords, &block)
         define('response', name.inspect) do
-          response_model = @meta_model.add_response(name, keywords)
-          Response.new(response_model, &block) if block
+          @meta_model.add_response(name, keywords).tap do |response_model|
+            Response.new(response_model, &block) if block
+          end
         end
       end
 
@@ -215,8 +227,9 @@ module Jsapi
       # See Meta::Definitions#schemas for further information.
       def schema(name, **keywords, &block)
         define('schema', name.inspect) do
-          schema_model = @meta_model.add_schema(name, keywords)
-          Schema.new(schema_model, &block) if block
+          @meta_model.add_schema(name, keywords).tap do |schema_model|
+            Schema.new(schema_model, &block) if block
+          end
         end
       end
 
@@ -247,8 +260,9 @@ module Jsapi
       # See Meta::Definitions#security_schemes for further information.
       def security_scheme(name, **keywords, &block)
         define('security_scheme', name.inspect) do
-          security_scheme = @meta_model.add_security_scheme(name, keywords)
-          Base.new(security_scheme, &block) if block
+          @meta_model.add_security_scheme(name, keywords).tap do |security_scheme|
+            Base.new(security_scheme, &block) if block
+          end
         end
       end
 

data/lib/jsapi/dsl/operation.rb

@@ -4,6 +4,7 @@ module Jsapi
   module DSL
     # Used to define an API operation.
     class Operation < Base
+      include SharedOperationMethods
 
       # Specifies a callback.
       #
@@ -26,15 +27,16 @@ module Jsapi
           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
+          @meta_model.add_callback(name, keywords).tap do |callback_model|
+            Base.new(callback_model, &block) if block
+          end
         end
       end
 
       ##
       # :method: deprecated
       # :args: arg
-      # Specifies whether or not the operation is deprecated.
+      # Specifies whether the operation is marked as deprecated.
       #
       #   deprecated true
 
@@ -61,116 +63,11 @@ module Jsapi
         keyword(:method, arg)
       end
 
-      # Defines the model class to access top-level parameters by.
-      #
-      #   model Foo do
-      #     def bar
-      #       # ...
-      #     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.
-      def model(klass = nil, &block)
-        if block
-          klass = Class.new(klass || Model::Base)
-          klass.class_eval(&block)
-        end
-        @meta_model.model = klass
-      end
-
-      # Specifies a parameter
-      #
-      #   parameter 'foo', type: 'string'
-      #
-      #   parameter 'foo', type: 'object' do
-      #     property 'bar', type: 'string'
-      #   end
-      #
-      # 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.
-      #
-      #   parameter 'foo'
-      #
-      # See Meta::Operation#parameters for further information.
-      def parameter(name = nil, **keywords, &block)
-        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)
-          Parameter.new(parameter_model, &block) if block
-        end
-      end
-
       ##
       # :method: path
       # :args: arg
       # Specifies the relative path of the operation.
 
-      # Specifies the request body.
-      #
-      #   request_body type: 'object' do
-      #     property 'foo', type: 'string'
-      #   end
-      #
-      # 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
-      # keywords nor a block is specified.
-      #
-      #   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
-          RequestBody.new(@meta_model.request_body, &block) if block
-        end
-      end
-
-      # Specifies a response.
-      #
-      #   response 200, type: 'object' do
-      #     property 'foo', type: 'string'
-      #   end
-      #
-      # 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 can't be specified together with keywords " \
-                       'or a block' if name && (keywords.any? || block)
-
-          if keywords.any? || block
-            status = status_or_name
-          else
-            status = status_or_name if name
-            keywords = { ref: name || status_or_name }
-          end
-          response_model = @meta_model.add_response(status, keywords)
-          Response.new(response_model, &block) if block
-        end
-      end
-
       ##
       # :method: security_requirement
       # :args: **keywords, &block
@@ -182,10 +79,14 @@ module Jsapi
       #
       # See Meta::Operation#security_requirements for further information.
 
+      # :method: server
+      # :args: arg
+      # Specifies a server providing the operation.
+
       ##
       # :method: summary
       # :args: arg
-      # Specifies the short summary of the operation.
+      # Specifies the short description of the operation.
 
       ##
       # :method: tag

data/lib/jsapi/dsl/parameter.rb

@@ -9,7 +9,7 @@ module Jsapi
       ##
       # :method: deprecated
       # :args: arg
-      # Specifies whether or not the parameter is deprecated.
+      # Specifies whether the parameter is marked as deprecated.
       #
       #   deprecated true
 

data/lib/jsapi/dsl/path.rb

@@ -3,7 +3,14 @@
 module Jsapi
   module DSL
     class Path < Base
-      # Specifies an operation within the current path.
+      include SharedOperationMethods
+
+      ##
+      # :method: description
+      # :args: arg
+      # Specifies the common description for all operations in this path.
+
+      # Specifies an operation within this path.
       #
       #   operation 'foo' do
       #     parameter 'bar', type: 'string'
@@ -14,30 +21,46 @@ module Jsapi
       #
       def operation(name = nil, **keywords, &block)
         define('operation', name&.inspect) do
-          operation_model = @meta_model.owner.add_operation(name, @meta_model.name, keywords)
-          Operation.new(operation_model, &block) if block
-        end
-      end
-
-      # Specifies a parameter applicable for all operations in this path.
-      #
-      #   parameter 'foo', type: 'string'
-      #
-      # See Meta::Path#parameters for further information.
-      def parameter(name, **keywords, &block)
-        define('parameter', name.inspect) do
-          parameter_model = @meta_model.add_parameter(name, keywords)
-          Parameter.new(parameter_model, &block) if block
+          @meta_model.owner.add_operation(name, @meta_model.name, keywords)
+                           .tap do |operation_model|
+            Operation.new(operation_model, &block) if block
+          end
         end
       end
 
       # Specifies a nested path.
-      def path(name = nil, &block)
+      def path(name = nil, **keywords, &block)
         define('path', name&.inspect) do
-          path_model = @meta_model.owner.add_path(@meta_model.name + name.to_s)
-          Path.new(path_model, &block) if block
+          name = @meta_model.name + name.to_s
+
+          @meta_model.owner.add_path(name, keywords).tap do |path_model|
+            Path.new(path_model, &block) if block
+          end
         end
       end
+
+      # :method: server
+      # :args: arg
+      # Specifies a server providing all operations in this path.
+
+      ##
+      # :method: summary
+      # :args: arg
+      # Specifies the common summary for all operations in this path.
+
+      ##
+      # :method: tag
+      # :args: name
+      # Adds a tag.
+      #
+      #   tag 'foo'
+
+      ##
+      # :method: tags
+      # :args: names
+      # Specifies all tags at once.
+      #
+      #   tags %w[foo bar]
     end
   end
 end

data/lib/jsapi/dsl/request_body.rb

@@ -9,7 +9,7 @@ module Jsapi
       ##
       # :method: deprecated
       # :args: arg
-      # Specifies whether or not the request body is deprecated.
+      # Specifies whether the request body is marked as deprecated.
       #
       #   deprecated true
 

data/lib/jsapi/dsl/response.rb

@@ -9,7 +9,7 @@ module Jsapi
       ##
       # :method: deprecated
       # :args: arg
-      # Specifies whether or not the response is deprecated.
+      # Specifies whether the response is marked as deprecated.
       #
       #   deprecated true
 
@@ -37,8 +37,9 @@ module Jsapi
           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
+          @meta_model.add_header(name, keywords).tap do |header_model|
+            Base.new(header_model, &block) if block
+          end
         end
       end
 
@@ -60,15 +61,17 @@ module Jsapi
           name = keywords[:ref] if name.nil?
           keywords = { ref: name } unless keywords.any? || block
 
-          link_model = @meta_model.add_link(name, keywords)
-          Base.new(link_model, &block) if block
+          @meta_model.add_link(name, keywords).tap do |link_model|
+            Base.new(link_model, &block) if block
+          end
         end
       end
 
       ##
       # :method: locale
       # :args: arg
-      # Specifies the locale to be used when producing a response.
+      # Specifies the locale to be used instead of the default locale when
+      # producing a response.
       #
       #   locale :en
     end

data/lib/jsapi/dsl/schema.rb

@@ -40,7 +40,7 @@ module Jsapi
       ##
       # :method: deprecated
       # :args: arg
-      # Specifies whether or not the schema is deprecated.
+      # Specifies whether the schema is marked as deprecated.
       #
       #   deprecated true
 
@@ -102,8 +102,13 @@ module Jsapi
           raise Error, "items isn't supported for '#{@meta_model.type}'"
         end
 
-        @meta_model.items = keywords
-        Schema.new(@meta_model.items, &block) if block
+        define do
+          @meta_model.items = keywords
+
+          @meta_model.items.tap do |items|
+            Schema.new(items, &block) if block
+          end
+        end
       end
 
       ##
@@ -209,8 +214,9 @@ module Jsapi
             raise Error, "property isn't supported for '#{@meta_model.type}'"
           end
 
-          property_model = @meta_model.add_property(name, keywords)
-          Schema.new(property_model, &block) if block
+          @meta_model.add_property(name, keywords).tap do |property_model|
+            Schema.new(property_model, &block) if block
+          end
         end
       end