jsapi 0.2.0 → 0.4.0

data/lib/jsapi/meta/openapi/root.rb

@@ -5,6 +5,8 @@ module Jsapi
     module OpenAPI
       # Represents an \OpenAPI object.
       class Root < Base
+        include Extensions
+
         ##
         # :attr: callbacks
         # The reusable Callback objects. Applies to \OpenAPI 3.0 and higher.
@@ -29,6 +31,11 @@ module Jsapi
         # The optional ExternalDocumentation object.
         attribute :external_docs, ExternalDocumentation
 
+        ##
+        # :attr: headers
+        # The reusable Header objects. Applies to \OpenAPI 3.0 and higher.
+        attribute :headers, { String => Header }
+
         ##
         # :attr: host
         # The host serving the API. Applies to \OpenAPI 2.0.
@@ -95,38 +102,43 @@ module Jsapi
               value.to_openapi(version)
             end
 
-          if version.major == 2
-            uri = servers&.first&.then { |server| URI(server.url) }
-            {
-              swagger: '2.0',
-              info: info&.to_openapi,
-              host: host || uri&.hostname,
-              basePath: base_path || uri&.path,
-              schemes: schemes || uri&.scheme&.then { |scheme| [scheme] },
-              consumes: consumed_mime_types,
-              produces: produced_mime_types,
-              securityDefinitions: security_schemes,
-              security: security_requirements&.map(&:to_openapi),
-              tags: tags&.map(&:to_openapi),
-              externalDocs: external_docs&.to_openapi
-            }
-          else
-            {
-              openapi: version.minor.zero? ? '3.0.3' : '3.1.0',
-              info: info&.to_openapi,
-              servers: servers&.map(&:to_openapi),
-              components: {
-                callbacks: callbacks&.transform_values do |callback|
-                  callback.to_openapi(version, definitions)
-                end,
-                links: links&.transform_values(&:to_openapi),
-                securitySchemes: security_schemes
-              }.compact.presence,
-              security: security_requirements&.map(&:to_openapi),
-              tags: tags&.map(&:to_openapi),
-              externalDocs: external_docs&.to_openapi
-            }
-          end.compact
+          with_openapi_extensions(
+            if version.major == 2
+              uri = servers&.first&.then { |server| URI(server.url) }
+              {
+                swagger: '2.0',
+                info: info&.to_openapi,
+                host: host || uri&.hostname,
+                basePath: base_path || uri&.path,
+                schemes: schemes || uri&.scheme&.then { |scheme| [scheme] },
+                consumes: consumed_mime_types,
+                produces: produced_mime_types,
+                securityDefinitions: security_schemes,
+                security: security_requirements&.map(&:to_openapi),
+                tags: tags&.map(&:to_openapi),
+                externalDocs: external_docs&.to_openapi
+              }
+            else
+              {
+                openapi: version.minor.zero? ? '3.0.3' : '3.1.0',
+                info: info&.to_openapi,
+                servers: servers&.map(&:to_openapi),
+                components: {
+                  callbacks: callbacks&.transform_values do |callback|
+                    callback.to_openapi(version, definitions)
+                  end,
+                  headers: headers&.transform_values do |header|
+                    header.to_openapi(version)
+                  end,
+                  links: links&.transform_values(&:to_openapi),
+                  securitySchemes: security_schemes
+                }.compact.presence,
+                security: security_requirements&.map(&:to_openapi),
+                tags: tags&.map(&:to_openapi),
+                externalDocs: external_docs&.to_openapi
+              }
+            end
+          )
         end
       end
     end

data/lib/jsapi/meta/openapi/security_requirement.rb

@@ -17,7 +17,7 @@ module Jsapi
         # The schemes.
         attribute :schemes, { String => Scheme }
 
-        # Returns a hash representing the security requirement object.
+        # Returns a hash representing the \OpenAPI security requirement object.
         def to_openapi(*)
           schemes&.transform_values(&:scopes) || {}
         end

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

@@ -6,6 +6,8 @@ module Jsapi
       module SecurityScheme
         # Represents a security scheme based on an API key.
         class APIKey < Base
+          include Extensions
+
           ##
           # :attr: in
           # The location of the API key. Possible values are:
@@ -22,14 +24,14 @@ module Jsapi
           # API key is sent by.
           attribute :name, String
 
-          # Returns a hash representing the security scheme object.
+          # Returns a hash representing the \OpenAPI security scheme object.
           def to_openapi(*)
-            {
+            with_openapi_extensions(
               type: 'apiKey',
               name: name,
               in: self.in,
               description: description
-            }.compact
+            )
           end
         end
       end

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

@@ -7,21 +7,26 @@ module Jsapi
         module HTTP
           # Represents a security scheme based on \HTTP basic authentication.
           class Basic < Base
-            # Returns a hash representing the security scheme object.
+            include Extensions
+
+            # Returns a hash representing the \OpenAPI security scheme object.
             def to_openapi(version)
               version = OpenAPI::Version.from(version)
-              if version.major == 2
-                {
-                  type: 'basic',
-                  description: description
-                }
-              else
-                {
-                  type: 'http',
-                  scheme: 'basic',
-                  description: description
-                }
-              end.compact
+
+              with_openapi_extensions(
+                if version.major == 2
+                  {
+                    type: 'basic',
+                    description: description
+                  }
+                else
+                  {
+                    type: 'http',
+                    scheme: 'basic',
+                    description: description
+                  }
+                end
+              )
             end
           end
         end

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

@@ -11,23 +11,25 @@ module Jsapi
           # Thus, a security scheme of this class is skipped when generating
           # an \OpenAPI 2.0 document.
           class Bearer < Base
+            include Extensions
+
             ##
             # :attr: bearer_format
             # The optional format of the bearer token.
             attribute :bearer_format, String
 
-            # Returns a hash representing the security scheme object, or
+            # 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
-              }.compact
+              )
             end
           end
         end

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

@@ -12,22 +12,24 @@ module Jsapi
           # a security scheme of this class is skipped when generating an
           # \OpenAPI 2.0 document.
           class Other < Base
+            include Extensions
+
             ##
             # :attr: scheme
             # The mandatory \HTTP authentication scheme.
             attribute :scheme, String
 
-            # Returns a hash representing the security scheme object, or +nil+
+            # 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
-              }.compact
+              )
             end
           end
         end

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

@@ -6,6 +6,8 @@ module Jsapi
       module SecurityScheme
         # Represents a security scheme based on \OAuth2.
         class OAuth2 < Base
+          include Extensions
+
           ##
           # :attr: oauth_flows
           # The hash containing the OAuth flows. Possible keys are:
@@ -19,13 +21,11 @@ module Jsapi
           attribute :oauth_flows, { String => OAuthFlow },
                     keys: %w[authorization_code client_credentials implicit password]
 
-          # Returns a hash representing the security scheme object.
+          # Returns a hash representing the \OpenAPI security scheme object.
           def to_openapi(version)
             version = Version.from(version)
-            {
-              type: 'oauth2',
-              description: description
-            }.tap do |h|
+
+            with_openapi_extensions(type: 'oauth2', description: description).tap do |h|
               if oauth_flows&.any?
                 if version.major == 2
                   key, oauth_flow = oauth_flows.first
@@ -37,7 +37,7 @@ module Jsapi
                   end
                 end
               end
-            end.compact
+            end
           end
         end
       end

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

@@ -9,21 +9,23 @@ module Jsapi
         # 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 Extensions
+
           ##
           # :attr: open_id_connect_url
           attribute :open_id_connect_url, String
 
-          # Returns a hash representing the security scheme object, or +nil+
+          # Returns a hash representing the \OpenAPI security scheme object, or +nil+
           # if <code>version.major</code> is 2.
           def to_openapi(version)
             version = Version.from(version)
             return if version.major == 2
 
-            {
+            with_openapi_extensions(
               type: 'openIdConnect',
               openIdConnectUrl: open_id_connect_url,
               description: description
-            }.compact
+            )
           end
         end
       end

data/lib/jsapi/meta/openapi/server.rb

@@ -5,6 +5,8 @@ module Jsapi
     module OpenAPI
       # Represents a server object.
       class Server < Base
+        include Extensions
+
         ##
         # :attr: description
         # The optional description of the server.
@@ -20,13 +22,13 @@ module Jsapi
         # The optional server variables.
         attribute :variables, { String => ServerVariable }
 
-        # Returns a hash representing the server object.
+        # Returns a hash representing the \OpenAPI server object.
         def to_openapi(*)
-          {
+          with_openapi_extensions(
             url: url,
             description: description,
             variables: variables&.transform_values(&:to_openapi)
-          }.compact
+          )
         end
       end
     end

data/lib/jsapi/meta/openapi/server_variable.rb

@@ -5,6 +5,8 @@ module Jsapi
     module OpenAPI
       # Represents a server variable object.
       class ServerVariable < Base
+        include Extensions
+
         ##
         # :attr: default
         # The default value of the server variable.
@@ -20,13 +22,13 @@ module Jsapi
         # The values of the server variable.
         attribute :enum, [String]
 
-        # Returns a hash representing the server variable object.
+        # Returns a hash representing the \OpenAPI server variable object.
         def to_openapi(*)
-          {
+          with_openapi_extensions(
             default: default,
             enum: enum.presence, # must not be empty
             description: description
-          }.compact
+          )
         end
       end
     end

data/lib/jsapi/meta/openapi/tag.rb

@@ -5,6 +5,8 @@ module Jsapi
     module OpenAPI
       # Represents a tag object.
       class Tag < Base
+        include Extensions
+
         ##
         # :attr: description
         # The description of the tag.
@@ -20,13 +22,13 @@ module Jsapi
         # The name of the tag.
         attribute :name, String
 
-        # Returns a hash representing the tag object.
+        # Returns a hash representing the \OpenAPI tag object.
         def to_openapi(*)
-          {
+          with_openapi_extensions(
             name: name,
             description: description,
             externalDocs: external_docs&.to_openapi
-          }.compact
+          )
         end
       end
     end

data/lib/jsapi/meta/openapi.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
+require_relative 'openapi/extensions'
 require_relative 'openapi/version'
 require_relative 'openapi/callback'
 require_relative 'openapi/contact'
 require_relative 'openapi/license'
 require_relative 'openapi/info'
+require_relative 'openapi/example'
 require_relative 'openapi/external_documentation'
+require_relative 'openapi/header'
 require_relative 'openapi/oauth_flow'
 require_relative 'openapi/security_scheme'
 require_relative 'openapi/security_requirement'

data/lib/jsapi/meta/operation.rb

@@ -3,6 +3,8 @@
 module Jsapi
   module Meta
     class Operation < Base
+      include OpenAPI::Extensions
+
       ##
       # :attr: callbacks
       # The optional callbacks. Applies to \OpenAPI 3.0 and higher.
@@ -133,7 +135,8 @@ module Jsapi
       # Returns a hash representing the \OpenAPI operation object.
       def to_openapi(version, definitions)
         version = OpenAPI::Version.from(version)
-        {
+
+        with_openapi_extensions(
           operationId: name,
           tags: tags,
           summary: summary,
@@ -141,7 +144,7 @@ module Jsapi
           externalDocs: external_docs&.to_openapi,
           deprecated: deprecated?.presence,
           security: security_requirements&.map(&:to_openapi)
-        }.tap do |hash|
+        ).tap do |hash|
           if version.major == 2
             hash[:consumes] = consumed_mime_types if consumed_mime_types
             hash[:produces] = produced_mime_types if produced_mime_types
@@ -170,7 +173,7 @@ module Jsapi
               callback.to_openapi(version, definitions)
             end
           end
-        end.compact
+        end
       end
     end
   end

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

@@ -4,6 +4,8 @@ module Jsapi
   module Meta
     module Parameter
       class Model < Base
+        include OpenAPI::Extensions
+
         ##
         # :attr: deprecated
         # Specifies whether or not the parameter is deprecated.
@@ -17,7 +19,7 @@ module Jsapi
         ##
         # :attr_reader: examples
         # The examples.
-        attribute :examples, { String => Example }, default_key: 'default'
+        attribute :examples, { String => OpenAPI::Example }, default_key: 'default'
 
         ##
         # :attr: in
@@ -87,32 +89,34 @@ module Jsapi
           else
             parameter_name = schema.array? ? "#{name}[]" : name
             [
-              if version.major == 2
-                {
-                  name: parameter_name,
-                  in: self.in,
-                  description: description,
-                  required: required?.presence,
-                  allowEmptyValue: allow_empty_value?.presence,
-                  collectionFormat: ('multi' if schema.array?)
-                }.merge(schema.to_openapi(version))
-              else
-                {
-                  name: parameter_name,
-                  in: self.in,
-                  description: description,
-                  required: required?.presence,
-                  allowEmptyValue: allow_empty_value?.presence,
-                  deprecated: deprecated?.presence,
-                  schema: schema.to_openapi(version),
-                  examples: examples&.transform_values(&:to_openapi)
-
-                  # NOTE: collectionFormat is replaced by style and explode.
-                  #       The default values for query parameters are:
-                  #       - style: 'form'
-                  #       - explode: true
-                }
-              end.compact
+              with_openapi_extensions(
+                if version.major == 2
+                  {
+                    name: parameter_name,
+                    in: self.in,
+                    description: description,
+                    required: required?.presence,
+                    allowEmptyValue: allow_empty_value?.presence,
+                    collectionFormat: ('multi' if schema.array?)
+                  }.merge(schema.to_openapi(version))
+                else
+                  {
+                    name: parameter_name,
+                    in: self.in,
+                    description: description,
+                    required: required?.presence,
+                    allowEmptyValue: allow_empty_value?.presence,
+                    deprecated: deprecated?.presence,
+                    schema: schema.to_openapi(version),
+                    examples: examples&.transform_values(&:to_openapi)
+
+                    # NOTE: collectionFormat is replaced by style and explode.
+                    #       The default values for query parameters are:
+                    #       - style: 'form'
+                    #       - explode: true
+                  }
+                end
+              )
             ]
           end
         end
@@ -141,27 +145,29 @@ module Jsapi
               description = property_schema.description
               allow_empty_value = property.schema.existence <= Existence::ALLOW_EMPTY
               [
-                if version.major == 2
-                  {
-                    name: parameter_name,
-                    in: self.in,
-                    description: description,
-                    required: required,
-                    allowEmptyValue: allow_empty_value.presence,
-                    collectionFormat: ('multi' if property_schema.array?)
-                  }.merge(property_schema.to_openapi(version))
-                else
-                  {
-                    name: parameter_name,
-                    in: self.in,
-                    description: description,
-                    required: required,
-                    allowEmptyValue: allow_empty_value.presence,
-                    deprecated: deprecated,
-                    schema: property_schema.to_openapi(version).except(:deprecated),
-                    examples: examples&.transform_values(&:to_openapi)
-                  }
-                end.compact
+                with_openapi_extensions(
+                  if version.major == 2
+                    {
+                      name: parameter_name,
+                      in: self.in,
+                      description: description,
+                      required: required,
+                      allowEmptyValue: allow_empty_value.presence,
+                      collectionFormat: ('multi' if property_schema.array?)
+                    }.merge(property_schema.to_openapi(version))
+                  else
+                    {
+                      name: parameter_name,
+                      in: self.in,
+                      description: description,
+                      required: required,
+                      allowEmptyValue: allow_empty_value.presence,
+                      deprecated: deprecated,
+                      schema: property_schema.to_openapi(version).except(:deprecated),
+                      examples: examples&.transform_values(&:to_openapi)
+                    }
+                  end
+                )
               ]
             end
           end

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

@@ -4,6 +4,8 @@ module Jsapi
   module Meta
     module RequestBody
       class Model < Base
+        include OpenAPI::Extensions
+
         ##
         # :attr: description
         # The optional description of the request body.
@@ -12,7 +14,7 @@ module Jsapi
         ##
         # :attr_reader: examples
         # The optional examples.
-        attribute :examples, { String => Example }, default_key: 'default'
+        attribute :examples, { String => OpenAPI::Example }, default_key: 'default'
 
         ##
         # :attr_reader: schema
@@ -44,12 +46,12 @@ module Jsapi
             in: 'body',
             description: description,
             required: required?
-          }.merge(schema.to_openapi('2.0')).compact
+          }.merge(schema.to_openapi('2.0')).merge(openapi_extensions).compact
         end
 
         # Returns a hash representing the \OpenAPI 3.x request body object.
         def to_openapi(version)
-          {
+          with_openapi_extensions(
             description: description,
             content: {
               'application/json' => {
@@ -58,7 +60,7 @@ module Jsapi
               }.compact
             },
             required: required?
-          }.compact
+          )
         end
       end
     end