jsapi 0.8.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41bcc8f72dc668c6df55dfc73e6e2c9cc6fde569ebe008e503586100e0b3bba1
-  data.tar.gz: 9667a2661824e0d3a47675e835f3372cfd22bff71ab8c7bb3bde3c0e56cc78be
+  metadata.gz: 4631e17cbd92a36a62ab6e7aa139b65afa83fccc2c41da34c3f757f2b077340f
+  data.tar.gz: 4c547aeb52a0fc74c09389f2c97dd0b8c90883fd36c79b9c502689a25379f3f5
 SHA512:
-  metadata.gz: 576422bac22ee56e77ab160e50033a78ba1f02039fd5a7686583d0778f049e331892bb5d7692dcdc428c9b250706f13bf6e585db4472d40e31d63537116d9f37
-  data.tar.gz: e3ef8964a2a55d6f245a8982e7dcad76f564d066af119eec43edb1b5bc579f1771ce87e747924e5cd2d6b650e07e44515ff7e722860a4c4ee8c6fa7e8b0360cb
+  metadata.gz: 1db64f601b34597e5b13ee820482c5a72d2adef153feac7ef3e1141804df36cc8816f665ee18c73e1b30e50a8c13454bed4c7562d447b2fdaf1b3814d863bd09
+  data.tar.gz: a4bd27f4fcc7c50ee9447e70777ca54de3e81ee6fd7ab3124817baf54511c90d0d95cf461c09c7fdc42a3bf8b57bb62d91954bc96d8a44a77eb15f9d53d2f5be

data/lib/jsapi/configuration.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Jsapi
+  # Holds the \Jsapi configuration.
+  class Configuration
+    # The path where the API definitions are located relative to +Rails.root+.
+    # The default is <code>"app/api_defs"</code>.
+    attr_accessor :api_defs_path
+
+    def initialize # :nodoc:
+      @api_defs_path = 'app/api_defs'
+    end
+
+    # Returns the absolute +Pathname+ for +args+ within +api_defs_path+.
+    def pathname(*args)
+      return unless (root = Rails.root)
+
+      root.join(*[api_defs_path, args].flatten)
+    end
+  end
+
+  class << self
+    # The singleton \Jsapi configuration.
+    def configuration
+      @configuration ||= Configuration.new
+    end
+  end
+end

data/lib/jsapi/controller/methods.rb

@@ -162,7 +162,7 @@ module Jsapi
         (operation.model || Model::Base).new(
           Parameters.new(
             params.except(:action, :controller, :format).permit!,
-            headers,
+            request.headers,
             operation,
             definitions,
             strong: strong

data/lib/jsapi/dsl/base.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module DSL
+    class Base
+      def initialize(meta_model, pathname = nil, parent: nil, &block)
+        @meta_model = meta_model
+        @pathname = pathname
+        @parent = parent
+
+        # Raise an error when pathname is attempted to be imported again
+        if pathname && (ancestor = parent)
+          while ancestor
+            if ancestor.pathname == pathname
+              raise Error, "Attempted #{pathname.to_path.inspect} to be imported again"
+            end
+
+            ancestor = ancestor.parent
+          end
+        end
+
+        # Evaluate the file to be imported
+        instance_eval(pathname.read, pathname.to_path) if pathname
+
+        # Evaluate block
+        if block
+          if meta_model.reference?
+            raise Error, "reference can't be specified together with a block"
+          end
+
+          instance_eval(&block)
+        end
+      end
+
+      # Imports the file named +filename+ relative to +Jsapi.configation.path+.
+      def import(filename)
+        raise ArgumentError, "file name can't be blank" if filename.blank?
+
+        pathname = Jsapi.configuration.pathname("#{filename}.rb")
+        self.class.new(@meta_model, pathname, parent: self)
+      end
+
+      # Imports the file named +filename+ relative to the current file's path.
+      def import_relative(filename)
+        raise ArgumentError, "file name can't be blank" if filename.blank?
+
+        pathname = (@pathname&.parent || Jsapi.configuration.pathname) + "#{filename}.rb"
+        self.class.new(@meta_model, pathname, parent: self)
+      end
+
+      def respond_to_missing?(*args) # :nodoc:
+        keyword?(args.first)
+      end
+
+      protected
+
+      attr_reader :parent, :pathname
+
+      private
+
+      def define(*args, &block)
+        block.call
+      rescue Error => e
+        raise e.prepend_origin(args.compact.join(' '))
+      rescue StandardError => e
+        raise Error.new(e, args.compact.join(' ').presence)
+      end
+
+      def find_method(name)
+        ["#{name}=", "add_#{name}"].find do |method|
+          @meta_model.respond_to?(method)
+        end
+      end
+
+      def keyword(name, *params, &block)
+        method = find_method(name)
+        raise "unsupported keyword: #{name}" unless method
+
+        define(name) do
+          result = @meta_model.public_send(method, *params)
+          Base.new(result, &block) if block
+        end
+      end
+
+      def keyword?(name)
+        find_method(name).present?
+      end
+
+      alias method_missing keyword
+    end
+  end
+end

data/lib/jsapi/dsl/callback.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module DSL
+    # Used to specify an OpenAPI callback object.
+    class Callback < Base
+
+      # Adds a callback operation.
+      #
+      #   operation '{$request.query.foo}' do
+      #     parameter 'bar', type: 'string'
+      #   end
+      def operation(expression, **keywords, &block)
+        define('operation', expression.inspect) do
+          operation_model = @meta_model.add_operation(expression, keywords)
+          Operation.new(operation_model, &block) if block
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/dsl/class_methods.rb

@@ -3,35 +3,129 @@
 module Jsapi
   module DSL
     module ClassMethods
+      # Specifies the base path of the API.
+      #
+      #   api_base_path '/foo'
+      #
+      def api_base_path(arg)
+        api_definitions { base_path(arg) }
+      end
+
+      # Specifies a reusable callback.
+      #
+      #   api_callback 'onFoo' do
+      #     operation '{$request.query.foo}', path: '/bar'
+      #   end
+      #
+      def api_callback(name, **keywords, &block)
+        api_definitions { callback(name, **keywords, &block) }
+      end
+
       # Specifies the general default values for +type+.
       #
-      #   api_default 'array', read: [], write: []
+      #   api_default 'array', within_requests: [], within_responses: []
       #
       def api_default(type, **keywords, &block)
         api_definitions { default(type, **keywords, &block) }
       end
 
-      # The API definitions of the current class.
-      def api_definitions(&block)
-        @api_definitions ||= Meta::Definitions.new(
-          owner: self,
-          parent: superclass.try(:api_definitions)
-        )
+      # Returns the API definitions associated with the current class. Adds additional
+      # definitions when any keywords or a block is specified.
+      #
+      #   api_definitions base_path: '/foo' do
+      #     operation 'bar'
+      #   end
+      def api_definitions(**keywords, &block)
+        unless defined? @api_definitions
+          @api_definitions = Meta::Definitions.new(
+            owner: self,
+            parent: superclass.try(:api_definitions)
+          )
+          if (name = try(:name))
+            pathname = Jsapi.configuration.pathname(
+              name.deconstantize.split('::').map(&:underscore),
+              "#{name.demodulize.delete_suffix('Controller').underscore}.rb"
+            )
+            Definitions.new(@api_definitions, pathname) if pathname&.file?
+          end
+        end
+        @api_definitions.merge!(keywords) if keywords.any?
         Definitions.new(@api_definitions, &block) if block
+
         @api_definitions
       end
 
+      # Specifies a reusable example.
+      #
+      #   example 'foo', value: 'bar'
+      #
+      def api_example(name, **keywords, &block)
+        api_definitions { example(name, **keywords, &block) }
+      end
+
+      # Specifies the external documentation.
+      #
+      #   api_external_docs url: 'https://foo.bar'
+      #
+      def api_external_docs(**keywords, &block)
+        api_definitions { external_docs(**keywords, &block) }
+      end
+
+      # Specifies a reusable header.
+      #
+      #   api_header 'foo', type: 'string'
+      #
+      def api_header(name, **keywords, &block)
+        api_definitions { header(name, **keywords, &block) }
+      end
+
+      # Specifies the host serving the API.
+      #
+      #   api_host 'foo.bar'
+      #
+      def api_host(arg)
+        api_definitions { host(arg) }
+      end
+
+      # Imports the file named +filename+ relative to +Jsapi.configation.path+.
+      def api_import(filename)
+        api_definitions { import(filename) }
+      end
+
       # Includes API definitions from +klasses+.
       def api_include(*klasses)
         api_definitions { include(*klasses) }
       end
 
+      # Specifies general information about the API.
+      #
+      #   api_info title: 'Foo', version: '1' do
+      #     contact name: 'bar'
+      #   end
+      def api_info(**keywords, &block)
+        api_definitions { info(**keywords, &block) }
+      end
+
+      # Specifies a reusable link.
+      #
+      #   api_link 'foo', operation_id: 'bar'
+      #
+      def api_link(name, **keywords, &block)
+        api_definitions { link(name, **keywords, &block) }
+      end
+
       # Registers a callback to be called when rescuing an exception.
+      #
+      #   api_on_rescue :foo
+      #
+      #   api_on_rescue do |error|
+      #     # ...
+      #   end
       def api_on_rescue(method = nil, &block)
         api_definitions { on_rescue(method, &block) }
       end
 
-      # Defines an operation.
+      # Specifies an operation.
       #
       #   api_operation 'foo', path: '/foo' do
       #     parameter 'bar', type: 'string'
@@ -45,7 +139,7 @@ module Jsapi
         api_definitions { operation(name, **keywords, &block) }
       end
 
-      # Defines a reusable parameter.
+      # Specifies a reusable parameter.
       #
       #   api_parameter 'foo', type: 'string'
       #
@@ -70,7 +164,7 @@ module Jsapi
         api_definitions { rescue_from(*klasses, with: with) }
       end
 
-      # Defines a reusable response.
+      # Specifies a reusable response.
       #
       #   api_response 'Foo', type: 'object' do
       #     property 'bar', type: 'string'
@@ -79,7 +173,7 @@ module Jsapi
         api_definitions { response(name, **keywords, &block) }
       end
 
-      # Defines a reusable schema.
+      # Specifies a reusable schema.
       #
       #   api_schema 'Foo' do
       #     property 'bar', type: 'string'
@@ -88,13 +182,46 @@ module Jsapi
         api_definitions { schema(name, **keywords, &block) }
       end
 
-      # Defines the root of an OpenAPI document.
+      # Specifies a URI scheme supported by the API.
       #
-      #   openapi do
-      #     info title: 'Foo', version: '1'
+      #   api_scheme 'https'
+      #
+      def api_scheme(arg)
+        api_definitions { scheme(arg) }
+      end
+
+      # Specifies a security requirement.
+      #
+      #   api_security_requirement do
+      #     scheme 'basic_auth'
       #   end
-      def openapi(**keywords, &block)
-        api_definitions { openapi(**keywords, &block) }
+      #
+      def api_security_requirement(**keywords, &block)
+        api_definitions { security_requirement(**keywords, &block) }
+      end
+
+      # Specifies a security scheme.
+      #
+      #   api_security_scheme 'basic_auth', type: 'http', scheme: 'basic'
+      #
+      def api_security_scheme(name, **keywords, &block)
+        api_definitions { security_scheme(name, **keywords, &block) }
+      end
+
+      # Specifies a server providing the API.
+      #
+      #   api_server url: 'https://foo.bar/foo'
+      #
+      def api_server(**keywords, &block)
+        api_definitions { server(**keywords, &block) }
+      end
+
+      # Specifies a tag.
+      #
+      #   api_tag name: 'foo', description: 'description of foo'
+      #
+      def api_tag(**keywords, &block)
+        api_definitions { tag(**keywords, &block) }
       end
     end
   end

data/lib/jsapi/dsl/definitions.rb

@@ -3,46 +3,128 @@
 module Jsapi
   module DSL
     # Used to define top-level API components.
-    class Definitions < Node
+    class Definitions < Base
+      ##
+      # :method: base_path
+      # :args: arg
+      # Specifies the base path of the API.
+      #
+      #   base_path '/foo'
+      #
+      # See Meta::Definitions#base_path for further information.
+
+      # Specifies a reusable callback.
+      #
+      #   callback 'foo' do
+      #     operation '{$request.query.foo}', path: '/bar'
+      #   end
+      #
+      # 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
+        end
+      end
 
       # Specifies the general default values for +type+.
       #
-      #   default 'array', read: [], write: []
+      #   default 'array', within_requests: [], within_responses: []
       #
+      # See Meta::Definitions#defaults for further information.
       def default(type, **keywords, &block)
-        _define('default', type.inspect) do
-          default = _meta_model.add_default(type, keywords)
-          Node.new(default, &block) if block
+        define('default', type.inspect) do
+          default = @meta_model.add_default(type, keywords)
+          Base.new(default, &block) if block
         end
       end
 
+      # Specifies a reusable example.
+      #
+      #   example '/foo', value: 'bar'
+      #
+      # 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
+        end
+      end
+
+      ##
+      # :method: external_docs
+      # :args: **keywords, &block
+      # Specifies the external documentation.
+      #
+      #   external_docs url: 'https://foo.bar'
+      #
+      # See Meta::Definitions#external_docs for further information.
+
       # Includes API definitions from +klasses+.
       def include(*klasses)
         klasses.each do |klass|
-          _meta_model.include(klass.api_definitions)
+          @meta_model.include(klass.api_definitions)
         end
       end
 
-      # Registers a callback to be called when rescuing an exception.
-      def on_rescue(method = nil, &block)
-        _define('on_rescue') do
-          _meta_model.add_on_rescue(method || block)
+      # Specifies a reusable header.
+      #
+      #   header 'foo', type: 'string'
+      #
+      # 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
+        end
+      end
+
+      ##
+      # :method: host
+      # :args: arg
+      # Specifies the host serving the API.
+      #
+      #   host 'foo.bar'
+      #
+      # See Meta::Definitions#host for further information.
+
+      ##
+      # :method: info
+      # :args: **keywords, &block
+      # Specifies general information about the API.
+      #
+      #   info title: 'foo', version: 1 do
+      #     contact name: 'bar'
+      #   end
+      #
+      # See Meta::Definitions#info for further information.
+
+      # Specifies a reusable link.
+      #
+      #   link 'foo', operation_id: 'bar'
+      #
+      # 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
         end
       end
 
-      # Defines the root of an \OpenAPI document.
+      # Registers a callback to be called when rescuing an exception.
+      #
+      #   on_rescue :foo
       #
-      #   openapi do
-      #     info title: 'Foo', version: '1'
+      #   on_rescue do |error|
+      #     # ...
       #   end
-      def openapi(**keywords, &block)
-        _define('openapi') do
-          _meta_model.openapi = keywords
-          OpenAPI::Root.new(_meta_model.openapi, &block) if block
+      def on_rescue(method = nil, &block)
+        define('on_rescue') do
+          @meta_model.add_on_rescue(method || block)
         end
       end
 
-      # Defines an operation.
+      # Specifies an operation.
       #
       #   operation 'foo', path: '/foo' do
       #     parameter 'bar', type: 'string'
@@ -52,31 +134,35 @@ module Jsapi
       #   end
       #
       # +name+ can be +nil+ if the controller handles one operation only.
+      #
+      # 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)
+        define('operation', name&.inspect) do
+          operation_model = @meta_model.add_operation(name, keywords)
           Operation.new(operation_model, &block) if block
         end
       end
 
-      # Defines a reusable parameter.
+      # Specifies a reusable parameter.
       #
       #   parameter 'foo', type: 'string'
       #
+      # 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)
+        define('parameter', name.inspect) do
+          parameter_model = @meta_model.add_parameter(name, keywords)
           Parameter.new(parameter_model, &block) if block
         end
       end
 
-      # Defines a reusable request body.
+      # Specifies a reusable request body.
       #
       #   request_body 'foo', type: 'string'
       #
+      # 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)
+        define('request_body', name.inspect) do
+          request_body_model = @meta_model.add_request_body(name, keywords)
           RequestBody.new(request_body_model, &block) if block
         end
       end
@@ -88,33 +174,87 @@ module Jsapi
       #
       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: with })
         end
       end
 
-      # Defines a reusable response.
+      # Specifies a reusable response.
       #
       #   response 'Foo', type: 'object' do
       #     property 'bar', type: 'string'
       #   end
+      #
+      # 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)
+        define('response', name.inspect) do
+          response_model = @meta_model.add_response(name, keywords)
           Response.new(response_model, &block) if block
         end
       end
 
-      # Defines a reusable schema.
+      # Specifies a reusable schema.
       #
       #   schema 'Foo' do
       #     property 'bar', type: 'string'
       #   end
+      #
+      # 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)
+        define('schema', name.inspect) do
+          schema_model = @meta_model.add_schema(name, keywords)
           Schema.new(schema_model, &block) if block
         end
       end
+
+      ##
+      # :method: scheme
+      # :args: arg
+      # Specifies a URI scheme supported by the API.
+      #
+      #   scheme 'https'
+      #
+      # See Meta::Definitions#schemes for further information.
+
+      ##
+      # :method: security_requirement
+      # :args: **keywords, &block
+      # Adds a security requirement.
+      #
+      #   security_requirement do
+      #     scheme 'basic_auth'
+      #   end
+      #
+      # See Meta::Definitions#security_requirements for further information.
+
+      # Specifies a security scheme.
+      #
+      #   security_scheme 'basic_auth', type: 'http', scheme: 'basic'
+      #
+      # 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
+        end
+      end
+
+      ##
+      # :method: server
+      # :args: **keywords, &block
+      # Specifies a server providing the API.
+      #
+      #   server url: 'https://foo.bar/foo'
+      #
+      # See Meta::Definitions#servers for further information.
+
+      ##
+      # :method: tag
+      # :args: **keywords, &block
+      # Specifies a tag.
+      #
+      #   tag name: 'foo', description: 'description of foo'
+      #
+      # See Meta::Definitions#tags for further information.
     end
   end
 end