jsapi 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41bcc8f72dc668c6df55dfc73e6e2c9cc6fde569ebe008e503586100e0b3bba1
-  data.tar.gz: 9667a2661824e0d3a47675e835f3372cfd22bff71ab8c7bb3bde3c0e56cc78be
+  metadata.gz: e68467f73e8f1e909a03cd8c50f16674231dc0d070f05a5368b84e0f75dedfe6
+  data.tar.gz: 6c0b1304cb7192d223f517d5233fd96fa13aad7e0affb6832f313088bc3b3993
 SHA512:
-  metadata.gz: 576422bac22ee56e77ab160e50033a78ba1f02039fd5a7686583d0778f049e331892bb5d7692dcdc428c9b250706f13bf6e585db4472d40e31d63537116d9f37
-  data.tar.gz: e3ef8964a2a55d6f245a8982e7dcad76f564d066af119eec43edb1b5bc579f1771ce87e747924e5cd2d6b650e07e44515ff7e722860a4c4ee8c6fa7e8b0360cb
+  metadata.gz: 45b860d17ffc8f22cfbe4fca26d38e727ff87ddc93a959c6285fd1aaa8eb0de9c5e2a9c516f717f0f6d463b0bfe5c8708b9efa5bab5aa6b08eb642d90ee84d10
+  data.tar.gz: fe573b4b85e50373bd832f1ec3d4fdd9c11fe57bf42527fe80021d6c84d2271e01161b08cdedcee587a69bd43a28219562d36ed0c127197e4cbfe34e05902aca

data/lib/jsapi/dsl/base.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module DSL
+    class Base
+      def initialize(meta_model, &block)
+        @meta_model = meta_model
+
+        if block
+          if meta_model.reference?
+            raise Error, "reference can't be specified together with a block"
+          end
+
+          instance_eval(&block)
+        end
+      end
+
+      def respond_to_missing?(*args) # :nodoc:
+        keyword?(args.first)
+      end
+
+      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,9 +3,27 @@
 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) }
@@ -21,17 +39,72 @@ module Jsapi
         @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
+
       # 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 +118,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 +143,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 +152,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 +161,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.
+      #
+      #   api_scheme 'https'
+      #
+      def api_scheme(arg)
+        api_definitions { scheme(arg) }
+      end
+
+      # Specifies a security requirement.
       #
-      #   openapi do
-      #     info title: 'Foo', version: '1'
+      #   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

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