jsapi 2.1.2 → 3.0

data/lib/jsapi/{meta → definition}/server.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
+  module Definition
     # Specifies a server.
     class Server < Model::Base
       include OpenAPI::Extensions
@@ -39,6 +39,29 @@ module Jsapi
           variables: variables.transform_values(&:to_openapi).presence
         )
       end
+
+      # Builds the URL for +variables+.
+      def url_for(variables)
+        variables = variables&.with_indifferent_access || {}
+
+        url&.gsub(/\{\w+\}/) do |match|
+          name = match[1..-2]
+          value = variables[name]
+
+          server_variable = variable(name)
+          next value if server_variable.nil?
+          next server_variable.default if value.nil?
+
+          valid_values = server_variable.enum.presence
+          next value unless valid_values&.exclude?(value)
+
+          raise ArgumentError, Support::Messages.invalid_value(
+            name: name,
+            value: value,
+            valid_values: valid_values
+          )
+        end
+      end
     end
   end
 end

data/lib/jsapi/{meta → definition}/server_variable.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
+  module Definition
     # Specifies a server variable.
     class ServerVariable < Model::Base
       include OpenAPI::Extensions

data/lib/jsapi/{meta → definition}/tag.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
+  module Definition
     # Specifies a tag.
     class Tag < Model::Base
       include OpenAPI::Extensions

data/lib/jsapi/definition.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'definition/reference_error'
+require_relative 'definition/callable'
+require_relative 'definition/existence'
+require_relative 'definition/openapi'
+require_relative 'definition/model'
+require_relative 'definition/defaults'
+require_relative 'definition/example'
+require_relative 'definition/external_documentation'
+require_relative 'definition/tag'
+require_relative 'definition/server_variable'
+require_relative 'definition/server'
+require_relative 'definition/callback'
+require_relative 'definition/contact'
+require_relative 'definition/license'
+require_relative 'definition/info'
+require_relative 'definition/header'
+require_relative 'definition/oauth_flow'
+require_relative 'definition/security_scheme'
+require_relative 'definition/security_requirement'
+require_relative 'definition/link'
+require_relative 'definition/property'
+require_relative 'definition/schema'
+require_relative 'definition/content'
+require_relative 'definition/request_body'
+require_relative 'definition/parameter'
+require_relative 'definition/pathname'
+require_relative 'definition/response'
+require_relative 'definition/operation'
+require_relative 'definition/path'
+require_relative 'definition/rescue_handler'
+require_relative 'definition/api'

data/lib/jsapi/dsl/{definitions.rb → api.rb}

@@ -2,16 +2,16 @@
 
 module Jsapi
   module DSL
-    # Used to define top-level API components.
-    class Definitions < Base
+    # Used to define an \API.
+    class API < Base
       ##
       # :method: base_path
       # :args: arg
-      # Specifies the base path of the API.
+      # Specifies the base path of the \API.
       #
       #   base_path '/foo'
       #
-      # See Meta::Definitions#base_path for further information.
+      # See Definition::API#base_path for further information.
 
       # Specifies a reusable callback.
       #
@@ -19,10 +19,10 @@ module Jsapi
       #     operation '{$request.query.foo}', path: '/bar'
       #   end
       #
-      # See Meta::Definitions#callbacks for further information.
+      # See Definition::API#callbacks for further information.
       def callback(name, **keywords, &block)
         define('callback', name.inspect) do
-          @meta_model.add_callback(name, keywords).tap do |callback|
+          @definition.add_callback(name, keywords).tap do |callback|
             Base.new(callback, &block) if block
           end
         end
@@ -32,10 +32,10 @@ module Jsapi
       #
       #   default 'array', within_requests: [], within_responses: []
       #
-      # See Meta::Definitions#defaults for further information.
+      # See Definition::API#defaults for further information.
       def default(type, **keywords, &block)
         define('default', type.inspect) do
-          @meta_model.add_default(type, keywords).tap do |default|
+          @definition.add_default(type, keywords).tap do |default|
             Base.new(default, &block) if block
           end
         end
@@ -45,10 +45,10 @@ module Jsapi
       #
       #   example '/foo', value: 'bar'
       #
-      # See Meta::Definitions#examples for further information.
+      # See Definition::API#examples for further information.
       def example(name, **keywords, &block)
         define('example', name.inspect) do
-          @meta_model.add_example(name, keywords).tap do |example|
+          @definition.add_example(name, keywords).tap do |example|
             Base.new(example, &block) if block
           end
         end
@@ -61,12 +61,12 @@ module Jsapi
       #
       #   external_docs url: 'https://foo.bar'
       #
-      # See Meta::Definitions#external_docs for further information.
+      # See Definition::API#external_docs for further information.
 
-      # Includes API definitions from +klasses+.
+      # Includes \API components from +klasses+.
       def include(*klasses)
         klasses.each do |klass|
-          @meta_model.include(klass.api_definitions)
+          @definition.include(klass.api_definitions)
         end
       end
 
@@ -74,10 +74,10 @@ module Jsapi
       #
       #   header 'foo', type: 'string'
       #
-      # See Meta::Definitions#headers for further information.
+      # See Definition::API#headers for further information.
       def header(name, **keywords, &block)
         define('header', name.inspect) do
-          @meta_model.add_header(name, keywords).tap do |header|
+          @definition.add_header(name, keywords).tap do |header|
             Base.new(header, &block) if block
           end
         end
@@ -86,31 +86,31 @@ module Jsapi
       ##
       # :method: host
       # :args: arg
-      # Specifies the host serving the API.
+      # Specifies the host serving the \API.
       #
       #   host 'foo.bar'
       #
-      # See Meta::Definitions#host for further information.
+      # See Definition::API#host for further information.
 
       ##
       # :method: info
       # :args: **keywords, &block
-      # Specifies general information about the API.
+      # Specifies general information about the \API.
       #
       #   info title: 'foo', version: 1 do
       #     contact name: 'bar'
       #   end
       #
-      # See Meta::Definitions#info for further information.
+      # See Definition::API#info for further information.
 
       # Specifies a reusable link.
       #
       #   link 'foo', operation_id: 'bar'
       #
-      # See Meta::Definitions#links for further information.
+      # See Definition::API#links for further information.
       def link(name, **keywords, &block)
         define('link', name.inspect) do
-          @meta_model.add_link(name, keywords).tap do |link|
+          @definition.add_link(name, keywords).tap do |link|
             Base.new(link, &block) if block
           end
         end
@@ -125,7 +125,7 @@ module Jsapi
       #   end
       def on_rescue(method = nil, &block)
         define('on_rescue') do
-          @meta_model.add_on_rescue(method || block)
+          @definition.add_on_rescue(method || block)
         end
       end
 
@@ -140,11 +140,11 @@ module Jsapi
       #
       # +name+ can be +nil+ if the controller handles one operation only.
       #
-      # See Meta::Definitions#operations for further information.
+      # See Definition::API#operations for further information.
       def operation(name = nil, **keywords, &block)
         define('operation', name&.inspect) do
-          @meta_model.add_operation(name, keywords).tap do |operation_model|
-            Operation.new(operation_model, &block) if block
+          @definition.add_operation(name, keywords).tap do |operation_definition|
+            Operation.new(operation_definition, &block) if block
           end
         end
       end
@@ -153,11 +153,11 @@ module Jsapi
       #
       #   parameter 'foo', type: 'string'
       #
-      # See Meta::Definitions#parameters for further information.
+      # See Definition::API#parameters for further information.
       def parameter(name, **keywords, &block)
         define('parameter', name.inspect) do
-          @meta_model.add_parameter(name, keywords).tap do |parameter_model|
-            Parameter.new(parameter_model, &block) if block
+          @definition.add_parameter(name, keywords).tap do |parameter_definition|
+            Parameter.new(parameter_definition, &block) if block
           end
         end
       end
@@ -171,8 +171,8 @@ module Jsapi
       #
       def path(name = nil, **keywords, &block)
         define('path', name&.inspect) do
-          @meta_model.add_path(name, keywords).tap do |path_model|
-            Path.new(path_model, &block) if block
+          @definition.add_path(name, keywords).tap do |path_definition|
+            Path.new(path_definition, &block) if block
           end
         end
       end
@@ -181,11 +181,11 @@ module Jsapi
       #
       #   request_body 'foo', type: 'string'
       #
-      # See Meta::Definitions#request_bodies for further information.
+      # See Definition::API#request_bodies for further information.
       def request_body(name, **keywords, &block)
         define('request_body', name.inspect) do
-          @meta_model.add_request_body(name, keywords).tap do |request_body_model|
-            RequestBody.new(request_body_model, &block) if block
+          @definition.add_request_body(name, keywords).tap do |request_body_definition|
+            RequestBody.new(request_body_definition, &block) if block
           end
         end
       end
@@ -197,7 +197,7 @@ module Jsapi
       #
       def rescue_from(*klasses, with: nil)
         klasses.each do |klass|
-          @meta_model.add_rescue_handler(
+          @definition.add_rescue_handler(
             { error_class: klass, status_code: with }
           )
         end
@@ -209,11 +209,11 @@ module Jsapi
       #     property 'bar', type: 'string'
       #   end
       #
-      # See Meta::Definitions#responses for further information.
+      # See Definition::API#responses for further information.
       def response(name, **keywords, &block)
         define('response', name.inspect) do
-          @meta_model.add_response(name, keywords).tap do |response_model|
-            Response.new(response_model, &block) if block
+          @definition.add_response(name, keywords).tap do |response_definition|
+            Response.new(response_definition, &block) if block
           end
         end
       end
@@ -224,11 +224,11 @@ module Jsapi
       #     property 'bar', type: 'string'
       #   end
       #
-      # See Meta::Definitions#schemas for further information.
+      # See Definition::API#schemas for further information.
       def schema(name, **keywords, &block)
         define('schema', name.inspect) do
-          @meta_model.add_schema(name, keywords).tap do |schema_model|
-            Schema.new(schema_model, &block) if block
+          @definition.add_schema(name, keywords).tap do |schema_definition|
+            Schema.new(schema_definition, &block) if block
           end
         end
       end
@@ -236,11 +236,11 @@ module Jsapi
       ##
       # :method: scheme
       # :args: arg
-      # Specifies a URI scheme supported by the API.
+      # Specifies a URI scheme supported by the \API.
       #
       #   scheme 'https'
       #
-      # See Meta::Definitions#schemes for further information.
+      # See Definition::API#schemes for further information.
 
       ##
       # :method: security_requirement
@@ -251,16 +251,16 @@ module Jsapi
       #     scheme 'basic_auth'
       #   end
       #
-      # See Meta::Definitions#security_requirements for further information.
+      # See Definition::API#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.
+      # See Definition::API#security_schemes for further information.
       def security_scheme(name, **keywords, &block)
         define('security_scheme', name.inspect) do
-          @meta_model.add_security_scheme(name, keywords).tap do |security_scheme|
+          @definition.add_security_scheme(name, keywords).tap do |security_scheme|
             Base.new(security_scheme, &block) if block
           end
         end
@@ -269,11 +269,11 @@ module Jsapi
       ##
       # :method: server
       # :args: **keywords, &block
-      # Specifies a server providing the API.
+      # Specifies a server providing the \API.
       #
       #   server url: 'https://foo.bar/foo'
       #
-      # See Meta::Definitions#servers for further information.
+      # See Definition::API#servers for further information.
 
       ##
       # :method: tag
@@ -282,7 +282,7 @@ module Jsapi
       #
       #   tag name: 'foo', description: 'description of foo'
       #
-      # See Meta::Definitions#tags for further information.
+      # See Definition::API#tags for further information.
     end
   end
 end

data/lib/jsapi/dsl/base.rb

@@ -34,8 +34,8 @@ module Jsapi
     end
 
     class Base
-      def initialize(meta_model, pathname = nil, parent: nil, &block)
-        @meta_model = meta_model
+      def initialize(definition, pathname = nil, parent: nil, &block)
+        @definition = definition
         @pathname = pathname
         @parent = parent
 
@@ -55,7 +55,7 @@ module Jsapi
 
         # Evaluate block
         if block
-          if meta_model.reference?
+          if definition.reference?
             raise Error, "reference can't be specified together with a block"
           end
 
@@ -68,7 +68,7 @@ module Jsapi
         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)
+        self.class.new(@definition, pathname, parent: self)
       end
 
       # Imports the file named +filename+ relative to the current file's path.
@@ -76,7 +76,7 @@ module Jsapi
         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)
+        self.class.new(@definition, pathname, parent: self)
       end
 
       def respond_to_missing?(param1, *) # :nodoc:
@@ -105,7 +105,7 @@ module Jsapi
 
       def find_method(name)
         ["#{name}=", "add_#{name}"].find do |method|
-          @meta_model.respond_to?(method)
+          @definition.respond_to?(method)
         end
       end
 
@@ -114,7 +114,7 @@ module Jsapi
         raise "unsupported keyword: #{name}" unless method
 
         define(name) do
-          @meta_model.public_send(method, *params).tap do |result|
+          @definition.public_send(method, *params).tap do |result|
             Base.new(result, &block) if block
           end
         end

data/lib/jsapi/dsl/class_methods.rb

@@ -3,7 +3,35 @@
 module Jsapi
   module DSL
     module ClassMethods
-      # Specifies the base path of the API.
+      # Returns the \API definition associated with the current class. Defines it,
+      # if keywords or a block are passed.
+      #
+      #   api base_path: '/foo' do
+      #     operation 'bar'
+      #   end
+      def api(**keywords, &block)
+        unless defined? @api_definition
+          @api_definition = Definition::API.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"
+            )
+            API.new(@api_definition, pathname) if pathname&.file?
+          end
+        end
+        @api_definition.merge!(keywords) if keywords.any?
+        API.new(@api_definition, &block) if block
+
+        @api_definition
+      end
+
+      alias api_definitions api
+
+      # Specifies the base path of the \API.
       #
       #   api_base_path '/foo'
       #
@@ -29,32 +57,6 @@ module Jsapi
         api_definitions { default(type, **keywords, &block) }
       end
 
-      # 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'
@@ -79,7 +81,7 @@ module Jsapi
         api_definitions { header(name, **keywords, &block) }
       end
 
-      # Specifies the host serving the API.
+      # Specifies the host serving the \API.
       #
       #   api_host 'foo.bar'
       #
@@ -92,12 +94,12 @@ module Jsapi
         api_definitions { import(filename) }
       end
 
-      # Includes API definitions from +klasses+.
+      # Includes \API components from +klasses+.
       def api_include(*klasses)
         api_definitions { include(*klasses) }
       end
 
-      # Specifies general information about the API.
+      # Specifies general information about the \API.
       #
       #   api_info title: 'Foo', version: '1' do
       #     contact name: 'bar'
@@ -193,7 +195,7 @@ module Jsapi
         api_definitions { schema(name, **keywords, &block) }
       end
 
-      # Specifies a URI scheme supported by the API.
+      # Specifies a URI scheme supported by the \API.
       #
       #   api_scheme 'https'
       #
@@ -219,7 +221,7 @@ module Jsapi
         api_definitions { security_scheme(name, **keywords, &block) }
       end
 
-      # Specifies a server providing the API.
+      # Specifies a server providing the \API.
       #
       #   api_server url: 'https://foo.bar/foo'
       #

data/lib/jsapi/dsl/examples.rb

@@ -21,7 +21,7 @@ module Jsapi
             keywords = { value: name_or_value }
           end
 
-          example = @meta_model.add_example(name, keywords)
+          example = @definition.add_example(name, keywords)
           Base.new(example, &block) if block
         end
       end

data/lib/jsapi/dsl/operation.rb

@@ -21,14 +21,14 @@ module Jsapi
       #
       #   callback 'foo'
       #
-      # See Meta::Operation#callbacks for further information.
+      # See Definition::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
 
-          @meta_model.add_callback(name, keywords).tap do |callback_model|
-            Base.new(callback_model, &block) if block
+          @definition.add_callback(name, keywords).tap do |callback_definition|
+            Base.new(callback_definition, &block) if block
           end
         end
       end
@@ -47,18 +47,20 @@ module Jsapi
       #
       #    external_docs url: 'https://foo.bar/docs'
       #
-      # See Meta::Operation#external_docs for further information.
+      # See Definition::Operation#external_docs for further information.
 
       ##
       # :method: description
       # :args: arg
       # Specifies the description of the operation.
 
-      # Specifies the HTTP verb of the operation.
+      # Specifies the HTTP method of the operation.
       #
       #   method 'post'
       #
-      # See Meta::Operation#method for further information.
+      # See Definition::Operation#method for further information.
+      #
+      # Aliased as +http_method+.
       def method(arg)
         keyword(:method, arg)
       end
@@ -77,7 +79,7 @@ module Jsapi
       #     scheme 'basic_auth'
       #   end
       #
-      # See Meta::Operation#security_requirements for further information.
+      # See Definition::Operation#security_requirements for further information.
 
       # :method: server
       # :args: arg

data/lib/jsapi/dsl/parameter.rb

@@ -23,7 +23,7 @@ module Jsapi
       # :args: location
       # Specifies the location of the parameter.
       #
-      # See Meta::Parameter::Model#in for further information.
+      # See Definition::Parameter::Model#in for further information.
     end
   end
 end

data/lib/jsapi/dsl/path.rb

@@ -21,9 +21,11 @@ module Jsapi
       #
       def operation(name = nil, **keywords, &block)
         define('operation', name&.inspect) do
-          @meta_model.owner.add_operation(name, @meta_model.name, keywords)
-                           .tap do |operation_model|
-            Operation.new(operation_model, &block) if block
+          @definition
+            .owner
+            .add_operation(name, @definition.name, keywords)
+            .tap do |operation_definition|
+            Operation.new(operation_definition, &block) if block
           end
         end
       end
@@ -31,10 +33,10 @@ module Jsapi
       # Specifies a nested path.
       def path(name = nil, **keywords, &block)
         define('path', name&.inspect) do
-          name = @meta_model.name + name.to_s
+          name = @definition.name + name.to_s
 
-          @meta_model.owner.add_path(name, keywords).tap do |path_model|
-            Path.new(path_model, &block) if block
+          @definition.owner.add_path(name, keywords).tap do |path_definition|
+            Path.new(path_definition, &block) if block
           end
         end
       end

data/lib/jsapi/dsl/response.rb

@@ -31,14 +31,14 @@ module Jsapi
       #
       #   header 'x_foo'
       #
-      # See Meta::Response::Model#headers for further information.
+      # See Definition::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
 
-          @meta_model.add_header(name, keywords).tap do |header_model|
-            Base.new(header_model, &block) if block
+          @definition.add_header(name, keywords).tap do |header_definition|
+            Base.new(header_definition, &block) if block
           end
         end
       end
@@ -61,8 +61,8 @@ module Jsapi
           name = keywords[:ref] if name.nil?
           keywords = { ref: name } unless keywords.any? || block
 
-          @meta_model.add_link(name, keywords).tap do |link_model|
-            Base.new(link_model, &block) if block
+          @definition.add_link(name, keywords).tap do |link_definition|
+            Base.new(link_definition, &block) if block
           end
         end
       end