jsapi 0.7.3 → 0.9.0

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

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