jsapi 0.8.0 → 0.9.0

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Header
+      # Specifies a header object.
+      class Model < Base::Model
+        include OpenAPI::Extensions
+
+        delegate_missing_to :schema
+
+        ##
+        # :attr: collection_format
+        # The collection format of a header whose values are arrays. Possible values are:
+        #
+        # - <code>"csv"</code> -  comma separated values
+        # - <code>"pipes"</code> - pipe separated values
+        # - <code>"ssv"</code> - space separated values
+        # - <code>"tsv"</code> - tab separated values
+        #
+        # Applies to \OpenAPI 2.0.
+        attribute :collection_format, values: %w[csv pipes ssv tsv]
+
+        ##
+        # :attr: deprecated
+        # Specifies whether or not the header is deprecated.
+        attribute :deprecated, values: [true, false]
+
+        ##
+        # :attr: description
+        # The description of the header.
+        attribute :description, String
+
+        ##
+        # :attr_reader: examples
+        # One or more example values.
+        attribute :examples, { String => Example }, default_key: 'default'
+
+        ##
+        # :attr_reader: schema
+        # The Schema of the header.
+        attribute :schema, read_only: true
+
+        def initialize(keywords = {})
+          raise ArgumentError, "type can't be object" if keywords[:type] == 'object'
+
+          keywords = keywords.dup
+          super(
+            keywords.extract!(
+              :collection_format, :deprecated, :description, :examples, :openapi_extensions
+            )
+          )
+          add_example(value: keywords.delete(:example)) if keywords.key?(:example)
+
+          @schema = Schema.new(keywords)
+        end
+
+        # Returns a hash representing the \OpenAPI header object.
+        def to_openapi(version, *)
+          version = OpenAPI::Version.from(version)
+
+          with_openapi_extensions(
+            if version.major == 2
+              schema.to_openapi(version).merge(
+                collection_format: (collection_format if array?),
+                description: description
+              )
+            else
+              {
+                description: description,
+                deprecated: deprecated?.presence,
+                schema: schema.to_openapi(version),
+                examples: examples.transform_values(&:to_openapi).presence
+              }
+            end
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Header
+      class Reference < Base::Reference
+        # Returns a hash representing the \OpenAPI reference object.
+        def to_openapi(*)
+          { '$ref': "#/components/headers/#{ref}" }
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/header.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'header/model'
+require_relative 'header/reference'
+
+module Jsapi
+  module Meta
+    module Header
+      class << self
+        # Creates a Model or Reference.
+        def new(keywords = {})
+          return Reference.new(keywords) if keywords.key?(:ref)
+
+          Model.new(keywords)
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/info.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    # Specifies an info object.
+    class Info < Base::Model
+      include OpenAPI::Extensions
+
+      ##
+      # :attr: contact
+      # The Contact object.
+      attribute :contact, Contact
+
+      ##
+      # :attr: description
+      # The description of the API.
+      attribute :description, String
+
+      ##
+      # :attr: license
+      # The License object.
+      attribute :license, License
+
+      ##
+      # :attr: terms_of_service
+      # The URL pointing to the terms of service.
+      attribute :terms_of_service, String
+
+      ##
+      # :attr: title
+      # The title of the API.
+      attribute :title, String
+
+      ##
+      # :attr: version
+      # The version of the API.
+      attribute :version, String
+
+      # Returns a hash representing the \OpenAPI info object.
+      def to_openapi(*)
+        with_openapi_extensions(
+          title: title,
+          version: version,
+          description: description,
+          termsOfService: terms_of_service,
+          contact: contact&.to_openapi,
+          license: license&.to_openapi
+        )
+      end
+    end
+  end
+end

data/lib/jsapi/meta/license.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    # Specifies a license object.
+    class License < Base::Model
+      include OpenAPI::Extensions
+
+      ##
+      # :attr: name
+      # The name of the license.
+      attribute :name, String
+
+      ##
+      # :attr: url
+      # The URL of the license.
+      attribute :url, String
+
+      # Returns a hash representing the \OpenAPI license object.
+      def to_openapi(*)
+        with_openapi_extensions(name: name, url: url)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Link
+      # Specifies a link object.
+      class Model < Base::Model
+        include OpenAPI::Extensions
+
+        ##
+        # :attr: description
+        # The description of the link.
+        attribute :description, String
+
+        ##
+        # :attr: operation_id
+        # The operation ID.
+        attribute :operation_id, String
+
+        ##
+        # :attr: parameters
+        # The parameters to be passed.
+        attribute :parameters, { String => Object }
+
+        ##
+        # :attr: request_body
+        # The request body to be passed.
+        attribute :request_body
+
+        ##
+        # :attr: server
+        # The Server object.
+        attribute :server, Server
+
+        # Returns a hash representing the \OpenAPI link object.
+        def to_openapi(*)
+          with_openapi_extensions(
+            operationId: operation_id,
+            parameters: parameters.presence,
+            requestBody: request_body,
+            description: description,
+            server: server&.to_openapi
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Link
+      class Reference < Base::Reference
+        # Returns a hash representing the \OpenAPI reference object.
+        def to_openapi(*)
+          { '$ref': "#/components/links/#{ref}" }
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/link.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'link/model'
+require_relative 'link/reference'
+
+module Jsapi
+  module Meta
+    module Link
+      class << self
+        # Creates a Model or Reference.
+        def new(keywords = {})
+          return Reference.new(keywords) if keywords.key?(:ref)
+
+          Model.new(keywords)
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/oauth_flow.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    # Represents an OAuth flow object.
+    class OAuthFlow < Base::Model
+      include OpenAPI::Extensions
+
+      class Scope < Base::Model
+        ##
+        # :attr: description
+        # The description of the scope.
+        attribute :description, String, default: ''
+      end
+
+      ##
+      # :attr: authorization_url
+      # The authorization URL to be used for the flow.
+      attribute :authorization_url, String
+
+      ##
+      # :attr: refresh_url
+      # The refresh URL to be used for the flow.
+      #
+      # Note that the refresh URL was introduced with \OpenAPI 3.0. It is
+      # skipped when generating an \OpenAPI 2.0 document.
+      attribute :refresh_url, String
+
+      ##
+      # :attr: scopes
+      # The hash containing the scopes.
+      attribute :scopes, { String => Scope }
+
+      ##
+      # :attr: token_url
+      # The token URL to be used for the flow.
+      attribute :token_url, String
+
+      # Returns a hash representing the \OpenAPI OAuth flow object.
+      def to_openapi(version, *)
+        version = OpenAPI::Version.from(version)
+
+        with_openapi_extensions(
+          authorizationUrl: authorization_url,
+          tokenUrl: token_url,
+          refreshUrl: (refresh_url if version.major > 2),
+          scopes: scopes.transform_values(&:description)
+        )
+      end
+    end
+  end
+end

data/lib/jsapi/meta/openapi.rb

@@ -2,31 +2,3 @@
 
 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'
-require_relative 'openapi/server_variable'
-require_relative 'openapi/server'
-require_relative 'openapi/link'
-require_relative 'openapi/tag'
-require_relative 'openapi/root'
-
-module Jsapi
-  module Meta
-    module OpenAPI
-      class << self
-        # Creates a new \OpenAPI root object.
-        def new(keywords = {})
-          Root.new(keywords)
-        end
-      end
-    end
-  end
-end

data/lib/jsapi/meta/operation.rb

@@ -2,13 +2,14 @@
 
 module Jsapi
   module Meta
+    # Defines an API operation.
     class Operation < Base::Model
       include OpenAPI::Extensions
 
       ##
       # :attr: callbacks
-      # The optional callbacks. Applies to \OpenAPI 3.0 and higher.
-      attribute :callbacks, { String => OpenAPI::Callback }
+      # The Callback objects. Applies to \OpenAPI 3.0 and higher.
+      attribute :callbacks, { String => Callback }
 
       ##
       # :attr: deprecated
@@ -22,8 +23,8 @@ module Jsapi
 
       ##
       # :attr: external_docs
-      # The OpenAPI::ExternalDocumentation object.
-      attribute :external_docs, OpenAPI::ExternalDocumentation
+      # The ExternalDocumentation object.
+      attribute :external_docs, ExternalDocumentation
 
       ##
       # :attr: method
@@ -53,7 +54,7 @@ module Jsapi
       ##
       # :attr: parameters
       # The parameters of the operation.
-      attribute :parameters, { String => Parameter }, default: {}
+      attribute :parameters, { String => Parameter }
 
       ##
       # :attr: path
@@ -68,7 +69,7 @@ module Jsapi
       ##
       # :attr: responses
       # The responses of the operation.
-      attribute :responses, { String => Response }, default: {}, default_key: 'default'
+      attribute :responses, { String => Response }, default_key: 'default'
 
       ##
       # :attr: schemes
@@ -84,15 +85,15 @@ module Jsapi
 
       ##
       # :attr: security_requirements
-      # The OpenAPI::SecurityRequirement objects.
-      attribute :security_requirements, [OpenAPI::SecurityRequirement]
+      # The SecurityRequirement objects.
+      attribute :security_requirements, [SecurityRequirement]
 
       alias add_security add_security_requirement
 
       ##
       # :attr: servers
-      # The OpenAPI::Server objects. Applies to \OpenAPI 3.0 and higher.
-      attribute :servers, [OpenAPI::Server]
+      # The Server objects. Applies to \OpenAPI 3.0 and higher.
+      attribute :servers, [Server]
 
       ##
       # :attr: summary
@@ -104,13 +105,13 @@ module Jsapi
       # The tags used to group operations in an \OpenAPI document.
       attribute :tags, [String]
 
-      undef :add_parameter
-
       def initialize(name = nil, keywords = {})
         @name = name&.to_s
         super(keywords)
       end
 
+      undef add_parameter
+
       def add_parameter(name, keywords = {}) # :nodoc:
         (@parameters ||= {})[name.to_s] = Parameter.new(name, keywords)
       end
@@ -133,12 +134,12 @@ module Jsapi
 
         with_openapi_extensions(
           operationId: name,
-          tags: tags,
+          tags: tags.presence,
           summary: summary,
           description: description,
           externalDocs: external_docs&.to_openapi,
           deprecated: deprecated?.presence,
-          security: security_requirements&.map(&:to_openapi)
+          security: security_requirements.map(&:to_openapi).presence
         ).tap do |hash|
           if version.major == 2
             if (consumes = consumes(definitions)).present?
@@ -147,13 +148,13 @@ module Jsapi
             if (produces = produces(definitions)).present?
               hash[:produces] = produces
             end
-            hash[:schemes] = schemes if schemes
-          elsif servers
+            hash[:schemes] = schemes if schemes.present?
+          elsif servers.present?
             hash[:servers] = servers.map(&:to_openapi)
           end
           # Parameters (and request body)
           hash[:parameters] = parameters.values.flat_map do |parameter|
-            parameter.to_openapi(version, definitions)
+            parameter.to_openapi_parameters(version, definitions)
           end
           if request_body
             if version.major == 2
@@ -167,7 +168,7 @@ module Jsapi
             response.to_openapi(version, definitions)
           end
           # Callbacks
-          if callbacks && version.major > 2
+          if callbacks.present? && version.major > 2
             hash[:callbacks] = callbacks.transform_values do |callback|
               callback.to_openapi(version, definitions)
             end

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

@@ -3,7 +3,9 @@
 module Jsapi
   module Meta
     module Parameter
+      # Defines a parameter.
       class Model < Base::Model
+        include ToOpenAPI
         include OpenAPI::Extensions
 
         delegate_missing_to :schema
@@ -21,7 +23,7 @@ module Jsapi
         ##
         # :attr_reader: examples
         # The examples.
-        attribute :examples, { String => OpenAPI::Example }, default_key: 'default'
+        attribute :examples, { String => Example }, default_key: 'default'
 
         ##
         # :attr: in
@@ -74,7 +76,7 @@ module Jsapi
         end
 
         # Returns an array of hashes representing the \OpenAPI parameter objects.
-        def to_openapi(version, definitions)
+        def to_openapi_parameters(version, definitions)
           version = OpenAPI::Version.from(version)
           schema = self.schema.resolve(definitions)
 
@@ -109,7 +111,7 @@ module Jsapi
                     allowEmptyValue: allow_empty_value?.presence,
                     deprecated: deprecated?.presence,
                     schema: schema.to_openapi(version),
-                    examples: examples&.transform_values(&:to_openapi)
+                    examples: examples.transform_values(&:to_openapi).presence
 
                     # NOTE: collectionFormat is replaced by style and explode.
                     #       The default values for query parameters are:
@@ -165,7 +167,7 @@ module Jsapi
                       allowEmptyValue: allow_empty_value.presence,
                       deprecated: deprecated,
                       schema: property_schema.to_openapi(version).except(:deprecated),
-                      examples: examples&.transform_values(&:to_openapi)
+                      examples: examples.transform_values(&:to_openapi).presence
                     }
                   end
                 )

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

@@ -4,18 +4,20 @@ module Jsapi
   module Meta
     module Parameter
       class Reference < Base::Reference
-        # Returns an array of hashes. Each element represents an \OpenAPI parameter object
+        include ToOpenAPI
+
+        # Returns an array of hashes. Each hash represents an \OpenAPI parameter object
         # if the type of the referred parameter is <code>"object"</code>. Otherwise the
         # array contains a single hash representing the \OpenAPI reference object.
         #
-        # Raises a ReferenceError if the reference could not be resolved.
-        def to_openapi(version, definitions)
+        # Raises a ReferenceError when the reference could not be resolved.
+        def to_openapi_parameters(version, definitions)
           version = OpenAPI::Version.from(version)
           parameter = resolve(definitions)
 
           if parameter.schema.resolve(definitions).object?
             # Explode referred parameter
-            parameter.to_openapi(version, definitions)
+            parameter.to_openapi_parameters(version, definitions)
           else
             # Return an array containing the reference object
             path = version.major == 2 ? 'parameters' : 'components/parameters'

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Parameter
+      module ToOpenAPI
+        def to_openapi(version, definitions)
+          to_openapi_parameters(version, definitions).first
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/parameter.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'parameter/to_openapi'
 require_relative 'parameter/model'
 require_relative 'parameter/reference'
 
@@ -7,7 +8,7 @@ module Jsapi
   module Meta
     module Parameter
       class << self
-        # Creates a new parameter model or reference.
+        # Creates a Model or Reference.
         def new(name, keywords = {})
           return Reference.new(keywords) if keywords.key?(:ref)
 

data/lib/jsapi/meta/property.rb

@@ -56,7 +56,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)
 
         schema.to_openapi(version).tap do |hash|

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

@@ -3,6 +3,7 @@
 module Jsapi
   module Meta
     module RequestBody
+      # Defines a request body.
       class Model < Base::Model
         include OpenAPI::Extensions
 
@@ -15,13 +16,13 @@ module Jsapi
 
         ##
         # :attr: description
-        # The optional description of the request body.
+        # The description of the request body.
         attribute :description, String
 
         ##
         # :attr_reader: examples
-        # The optional examples.
-        attribute :examples, { String => OpenAPI::Example }, default_key: 'default'
+        # The Example objects.
+        attribute :examples, { String => Example }, default_key: 'default'
 
         ##
         # :attr_reader: schema
@@ -55,13 +56,13 @@ module Jsapi
         end
 
         # Returns a hash representing the \OpenAPI 3.x request body object.
-        def to_openapi(version)
+        def to_openapi(version, *)
           with_openapi_extensions(
             description: description,
             content: {
               content_type => {
                 schema: schema.to_openapi(version),
-                examples: examples&.transform_values(&:to_openapi)
+                examples: examples.transform_values(&:to_openapi).presence
               }.compact
             },
             required: required?

data/lib/jsapi/meta/request_body.rb

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