jsapi 0.8.0 → 0.9.1

data/lib/jsapi/meta/response/model.rb

@@ -3,6 +3,7 @@
 module Jsapi
   module Meta
     module Response
+      # Defines a response.
       class Model < Base::Model
         include OpenAPI::Extensions
 
@@ -15,23 +16,23 @@ module Jsapi
 
         ##
         # :attr: description
-        # The optional description of the response.
+        # The description of the response.
         attribute :description, String
 
         ##
         # :attr: examples
-        # The optional examples.
-        attribute :examples, { String => OpenAPI::Example }, default_key: 'default'
+        # The Example objects.
+        attribute :examples, { String => Example }, default_key: 'default'
 
         ##
         # :attr: headers
-        # The response headers.
-        attribute :headers, { String => OpenAPI::Header }
+        # The Header objects.
+        attribute :headers, { String => Header }
 
         ##
         # :attr: links
-        # The optional OpenAPI::Link objects.
-        attribute :links, { String => OpenAPI::Link }
+        # The Link objects.
+        attribute :links, { String => Link }
 
         ##
         # :attr: locale
@@ -66,11 +67,11 @@ module Jsapi
               {
                 description: description,
                 schema: schema.to_openapi(version),
-                headers: headers&.transform_values do |header|
+                headers: headers.transform_values do |header|
                   header.to_openapi(version) unless header.reference?
-                end&.compact,
+                end.compact.presence,
                 examples: (
-                  if (example = examples&.values&.first).present?
+                  if (example = examples.values.first).present?
                     { content_type => example.resolve(definitions).value }
                   end
                 )
@@ -81,11 +82,13 @@ module Jsapi
                 content: {
                   content_type => {
                     schema: schema.to_openapi(version),
-                    examples: examples&.transform_values(&:to_openapi)
+                    examples: examples.transform_values(&:to_openapi).presence
                   }.compact
                 },
-                headers: headers&.transform_values { |header| header.to_openapi(version) },
-                links: links&.transform_values(&:to_openapi)
+                headers: headers.transform_values do |header|
+                  header.to_openapi(version)
+                end.presence,
+                links: links.transform_values(&:to_openapi).presence
               }
             end
           )

data/lib/jsapi/meta/response.rb

@@ -7,7 +7,7 @@ module Jsapi
   module Meta
     module Response
       class << self
-        # Creates a new response model or reference.
+        # Creates a Model or Reference.
         def new(keywords = {})
           return Reference.new(keywords) if keywords.key?(:ref)
 

data/lib/jsapi/meta/schema/array.rb

@@ -43,7 +43,7 @@ module Jsapi
           super.merge(items: items&.to_json_schema || {})
         end
 
-        def to_openapi(version) # :nodoc:
+        def to_openapi(version, *) # :nodoc:
           super.merge(items: items&.to_openapi(version) || {})
         end
       end

data/lib/jsapi/meta/schema/base.rb

@@ -34,7 +34,7 @@ module Jsapi
         ##
         # :attr: external_docs
         # The OpenAPI::ExternalDocumentation object.
-        attribute :external_docs, OpenAPI::ExternalDocumentation
+        attribute :external_docs, ExternalDocumentation
 
         ##
         # :attr: existence
@@ -104,7 +104,7 @@ module Jsapi
         end
 
         # Returns a hash representing the \OpenAPI schema object.
-        def to_openapi(version)
+        def to_openapi(version, *)
           version = OpenAPI::Version.from(version)
 
           with_openapi_extensions(
@@ -112,21 +112,21 @@ module Jsapi
               # OpenAPI 2.0
               {
                 type: type,
-                example: examples&.first
+                example: examples.first
               }
             elsif version.minor.zero?
               # OpenAPI 3.0
               {
                 type: type,
                 nullable: nullable?.presence,
-                examples: examples,
+                examples: examples.presence,
                 deprecated: deprecated?.presence
               }
             else
               # OpenAPI 3.1
               {
                 type: nullable? ? [type, 'null'] : type,
-                examples: examples,
+                examples: examples.presence,
                 deprecated: deprecated?.presence
               }
             end.tap do |hash|

data/lib/jsapi/meta/schema/discriminator.rb

@@ -13,13 +13,13 @@ module Jsapi
         attribute :property_name, String
 
         # Returns a hash representing the \OpenAPI discriminator object.
-        def to_openapi(version)
+        def to_openapi(version, *)
           version = OpenAPI::Version.from(version)
           return property_name if version.major == 2
 
           {
             propertyName: property_name,
-            mapping: mappings&.transform_keys(&:to_s)
+            mapping: mappings.transform_keys(&:to_s).presence
           }.compact
         end
       end

data/lib/jsapi/meta/schema/object.rb

@@ -11,7 +11,7 @@ module Jsapi
 
         ##
         # :attr: all_of_references
-        attribute :all_of_references, [Reference], default: []
+        attribute :all_of_references, [Reference]
 
         alias :all_of= :all_of_references= # :nodoc:
         alias :add_all_of :add_all_of_reference
@@ -30,7 +30,7 @@ module Jsapi
         ##
         # :attr: properties
         # The properties.
-        attribute :properties, { String => Property }, default: {}
+        attribute :properties, { String => Property }
 
         undef add_property
 
@@ -83,7 +83,7 @@ module Jsapi
           ).compact
         end
 
-        def to_openapi(version) # :nodoc:
+        def to_openapi(version, *) # :nodoc:
           super.merge(
             allOf: all_of_references.map do |schema|
               schema.to_openapi(version)

data/lib/jsapi/meta/schema/reference.rb

@@ -22,7 +22,7 @@ module Jsapi
         end
 
         # Returns a hash representing the \OpenAPI reference object.
-        def to_openapi(version)
+        def to_openapi(version, *)
           version = OpenAPI::Version.from(version)
           path = version.major == 2 ? 'definitions' : 'components/schemas'
 

data/lib/jsapi/meta/schema.rb

@@ -27,8 +27,8 @@ module Jsapi
       end
 
       class << self
-        # Creates a new schema model or reference. The +:type+ keyword determines
-        # the type of the schema to be created. Possible types are:
+        # Creates a new schema. The +:type+ keyword determines the type of the schema to be
+        # created. Possible types are:
         #
         # - <code>"array"</code>
         # - <code>"boolean"</code>

data/lib/jsapi/meta/security_requirement.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    # Specifies a security requirement object.
+    class SecurityRequirement < Base::Model
+      class Scheme < Base::Model
+        ##
+        # :attr: scopes
+        # The array of scopes.
+        attribute :scopes, [String]
+      end
+
+      ##
+      # :attr_reader: schemes
+      # The schemes.
+      attribute :schemes, { String => Scheme }
+
+      # Returns a hash representing the \OpenAPI security requirement object.
+      def to_openapi(*)
+        schemes.transform_values(&:scopes)
+      end
+    end
+  end
+end

data/lib/jsapi/meta/security_scheme/api_key.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module SecurityScheme
+      # Specifies a security scheme based on an API key.
+      class APIKey < Base
+        include OpenAPI::Extensions
+
+        ##
+        # :attr: in
+        # The location of the API key. Possible values are:
+        #
+        # - <code>"cookie"</code>
+        # - <code>"header"</code>
+        # - <code>"query"</code>
+        #
+        attribute :in, String, values: %w[cookie header query]
+
+        ##
+        # :attr: name
+        # The name of the header, query parameter or cookie the
+        # API key is sent by.
+        attribute :name, String
+
+        # Returns a hash representing the \OpenAPI security scheme object.
+        def to_openapi(*)
+          with_openapi_extensions(
+            type: 'apiKey',
+            name: name,
+            in: self.in,
+            description: description
+          )
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/security_scheme/base.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module SecurityScheme
+      class Base < Meta::Base::Model
+        ##
+        # :attr: description
+        # The description of the security scheme.
+        attribute :description, String
+      end
+    end
+  end
+end

data/lib/jsapi/meta/security_scheme/http/basic.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module SecurityScheme
+      module HTTP
+        # Specifies a security scheme based on \HTTP basic authentication.
+        class Basic < Base
+          include OpenAPI::Extensions
+
+          # Returns a hash representing the \OpenAPI security scheme object.
+          def to_openapi(version, *)
+            version = OpenAPI::Version.from(version)
+
+            with_openapi_extensions(
+              if version.major == 2
+                {
+                  type: 'basic',
+                  description: description
+                }
+              else
+                {
+                  type: 'http',
+                  scheme: 'basic',
+                  description: description
+                }
+              end
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/security_scheme/http/bearer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module SecurityScheme
+      module HTTP
+        # Specifies a security scheme based on bearer authentication.
+        #
+        # Note that Bearer authentication was introduced with \OpenAPI 3.0. Thus, a security
+        # scheme of this class is skipped when generating an \OpenAPI 2.0 document.
+        class Bearer < Base
+          include OpenAPI::Extensions
+
+          ##
+          # :attr: bearer_format
+          # The format of the bearer token.
+          attribute :bearer_format, String
+
+          # Returns a hash representing the \OpenAPI security scheme object, or
+          # +nil+ if <code>version.major</code> is 2.
+          def to_openapi(version, *)
+            version = OpenAPI::Version.from(version)
+            return if version.major == 2
+
+            with_openapi_extensions(
+              type: 'http',
+              scheme: 'bearer',
+              bearerFormat: bearer_format,
+              description: description
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/security_scheme/http/other.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module SecurityScheme
+      module HTTP
+        # Specifies a security scheme based on any other \HTTP authentication than basic
+        # and bearer.
+        #
+        # Note that \OpenAPI 2.0 supports \HTTP basic authentication only. Thus, a security
+        # scheme of this class is skipped when generating an \OpenAPI 2.0 document.
+        class Other < Base
+          include OpenAPI::Extensions
+
+          ##
+          # :attr: scheme
+          # The mandatory \HTTP authentication scheme.
+          attribute :scheme, String
+
+          # Returns a hash representing the \OpenAPI security scheme object, or +nil+
+          # if <code>version.major</code> is 2.
+          def to_openapi(version, *)
+            version = OpenAPI::Version.from(version)
+            return if version.major == 2
+
+            with_openapi_extensions(
+              type: 'http',
+              scheme: scheme,
+              description: description
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/security_scheme/http.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'http/basic'
+require_relative 'http/bearer'
+require_relative 'http/other'
+
+module Jsapi
+  module Meta
+    module SecurityScheme
+      module HTTP
+        class << self
+          # Creates a new \HTTP authentication scheme.
+          def new(keywords = {})
+            scheme = keywords[:scheme] || 'basic'
+
+            case scheme.to_s
+            when 'basic'
+              HTTP::Basic.new(keywords.except(:scheme))
+            when 'bearer'
+              HTTP::Bearer.new(keywords.except(:scheme))
+            else
+              HTTP::Other.new(keywords)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/security_scheme/oauth2.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module SecurityScheme
+      # Specifies a security scheme based on \OAuth2.
+      class OAuth2 < Base
+        include OpenAPI::Extensions
+
+        ##
+        # :attr: oauth_flows
+        # The hash containing the OAuth flows. Possible keys are:
+        #
+        # - <code>"authorization_code"</code>
+        # - <code>"client_credentials"</code>
+        # - <code>"implicit"</code>
+        # - <code>"password"</code>
+        #
+        # Values are OAuthFlow objects.
+        attribute :oauth_flows, { String => OAuthFlow },
+                  keys: %w[authorization_code client_credentials implicit password]
+
+        # Returns a hash representing the \OpenAPI security scheme object.
+        def to_openapi(version, *)
+          version = OpenAPI::Version.from(version)
+
+          with_openapi_extensions(type: 'oauth2', description: description).tap do |h|
+            if oauth_flows.any?
+              if version.major == 2
+                key, oauth_flow = oauth_flows.first
+                h[:flow] = key.to_s
+                h.merge!(oauth_flow.to_openapi(version))
+              else
+                h[:flows] = oauth_flows.to_h do |key, value|
+                  [key.to_s.camelize(:lower).to_sym, value.to_openapi(version)]
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/security_scheme/open_id_connect.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module SecurityScheme
+      # Specifies a security scheme based on OpenID Connect.
+      #
+      # OpenID Connect was introduced with \OpenAPI 3.0. Thus, a security scheme of
+      # this class is skipped when generating an \OpenAPI 2.0 document.
+      class OpenIDConnect < Base
+        include OpenAPI::Extensions
+
+        ##
+        # :attr: open_id_connect_url
+        attribute :open_id_connect_url, String
+
+        # Returns a hash representing the \OpenAPI security scheme object, or +nil+
+        # if <code>version.major</code> is 2.
+        def to_openapi(version, *)
+          version = OpenAPI::Version.from(version)
+          return if version.major == 2
+
+          with_openapi_extensions(
+            type: 'openIdConnect',
+            openIdConnectUrl: open_id_connect_url,
+            description: description
+          )
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/security_scheme.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative 'security_scheme/base'
+require_relative 'security_scheme/api_key'
+require_relative 'security_scheme/http'
+require_relative 'security_scheme/oauth2'
+require_relative 'security_scheme/open_id_connect'
+
+module Jsapi
+  module Meta
+    module SecurityScheme
+      class << self
+        # Creates a security scheme. The +:type+ keyword specifies the type
+        # of the security scheme to be created. Possible types are:
+        #
+        # - <code>"api_key"</code>
+        # - <code>"basic"</code>
+        # - <code>"http"</code>
+        # - <code>"oauth2"</code>
+        # - <code>"open_id_connect"</code>
+        #
+        # Raises an InvalidArgumentError if the given type is invalid.
+        def new(keywords = {})
+          type = keywords[:type]
+          keywords = keywords.except(:type)
+
+          case type&.to_s
+          when 'api_key'
+            APIKey.new(keywords)
+          when 'basic' # OpenAPI 2.0
+            HTTP.new(keywords.merge(scheme: 'basic'))
+          when 'http' # OpenAPI 3.0 and higher
+            HTTP.new(keywords)
+          when 'oauth2'
+            OAuth2.new(keywords)
+          when 'open_id_connect' # OpenAPI 3.0 and higher
+            OpenIDConnect.new(keywords)
+          else
+            raise InvalidArgumentError.new(
+              'type',
+              type,
+              valid_values: %w[api_key basic http oauth2 open_id_connect]
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/server.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    # Specifiess a server object.
+    class Server < Base::Model
+      include OpenAPI::Extensions
+
+      ##
+      # :attr: description
+      # The description of the server.
+      attribute :description, String
+
+      ##
+      # :attr: url
+      # The absolute or relative URL of the server.
+      attribute :url, String
+
+      ##
+      # :attr_reader: variables
+      # The ServerVariable objects.
+      attribute :variables, { String => ServerVariable }
+
+      # Returns a hash representing the \OpenAPI server object.
+      def to_openapi(*)
+        with_openapi_extensions(
+          url: url,
+          description: description,
+          variables: variables.transform_values(&:to_openapi).presence
+        )
+      end
+    end
+  end
+end

data/lib/jsapi/meta/server_variable.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    # Specifies a server variable object.
+    class ServerVariable < Base::Model
+      include OpenAPI::Extensions
+
+      ##
+      # :attr: default
+      # The default value of the server variable.
+      attribute :default, String
+
+      ##
+      # :attr: description
+      # The description of the server variable.
+      attribute :description, String
+
+      ##
+      # :attr: enum
+      # The values of the server variable.
+      attribute :enum, [String]
+
+      # Returns a hash representing the \OpenAPI server variable object.
+      def to_openapi(*)
+        with_openapi_extensions(
+          default: default,
+          enum: enum.presence,
+          description: description
+        )
+      end
+    end
+  end
+end

data/lib/jsapi/meta/tag.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    # Specifies a tag object.
+    class Tag < Base::Model
+      include OpenAPI::Extensions
+
+      ##
+      # :attr: description
+      # The description of the tag.
+      attribute :description, String
+
+      ##
+      # :attr: external_docs
+      # The ExternalDocumentation object.
+      attribute :external_docs, ExternalDocumentation
+
+      ##
+      # :attr: name
+      # The name of the tag.
+      attribute :name, String
+
+      # Returns a hash representing the \OpenAPI tag object.
+      def to_openapi(*)
+        with_openapi_extensions(
+          name: name,
+          description: description,
+          externalDocs: external_docs&.to_openapi
+        )
+      end
+    end
+  end
+end

data/lib/jsapi/meta.rb

@@ -3,9 +3,23 @@
 require_relative 'meta/reference_error'
 require_relative 'meta/callable'
 require_relative 'meta/existence'
+require_relative 'meta/openapi'
 require_relative 'meta/base'
 require_relative 'meta/defaults'
-require_relative 'meta/openapi'
+require_relative 'meta/example'
+require_relative 'meta/external_documentation'
+require_relative 'meta/tag'
+require_relative 'meta/server_variable'
+require_relative 'meta/server'
+require_relative 'meta/callback'
+require_relative 'meta/contact'
+require_relative 'meta/license'
+require_relative 'meta/info'
+require_relative 'meta/header'
+require_relative 'meta/oauth_flow'
+require_relative 'meta/security_scheme'
+require_relative 'meta/security_requirement'
+require_relative 'meta/link'
 require_relative 'meta/property'
 require_relative 'meta/schema'
 require_relative 'meta/request_body'