jsapi 0.1.1

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      module SecurityScheme
+        # Represents a security scheme based on \OAuth2.
+        class OAuth2 < Base
+          ##
+          # :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 security scheme object.
+          def to_openapi(version)
+            version = Version.from(version)
+            {
+              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.compact
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      module SecurityScheme
+        # Represents 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
+          ##
+          # :attr: open_id_connect_url
+          attribute :open_id_connect_url, String
+
+          # Returns a hash representing the 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
+
+            {
+              type: 'openIdConnect',
+              openIdConnectUrl: open_id_connect_url,
+              description: description
+            }.compact
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# 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 OpenAPI
+      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.x
+              HTTP.new(keywords)
+            when 'oauth2'
+              OAuth2.new(keywords)
+            when 'open_id_connect' # OpenAPI 3.x
+              OpenIDConnect.new(keywords)
+            else
+              raise InvalidArgumentError.new(
+                'type',
+                type,
+                %w[api_key basic http oauth2 open_id_connect]
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      # Represents a server variable object.
+      class ServerVariable < Base
+        ##
+        # :attr: default
+        # The default value of the server variable.
+        attribute :default, String
+
+        ##
+        # :attr: description
+        # The optional description of the server variable.
+        attribute :description, String
+
+        ##
+        # :attr: enum
+        # The values of the server variable.
+        attribute :enum, [String]
+
+        # Returns a hash representing the server variable object.
+        def to_openapi(*)
+          {
+            default: default,
+            enum: enum.presence, # must not be empty
+            description: description
+          }.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      # Represents a tag object.
+      class Tag < Base
+        ##
+        # :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 tag object.
+        def to_openapi(*)
+          {
+            name: name,
+            description: description,
+            externalDocs: external_docs&.to_openapi
+          }.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      class Version
+        def self.from(version)
+          return version if version.is_a?(Version)
+
+          case version
+          when '2.0', 2, nil
+            new(2, 0)
+          when '3.0', 3
+            new(3, 0)
+          when '3.1'
+            new(3, 1)
+          else
+            raise ArgumentError, "unsupported OpenAPI version: #{version.inspect}"
+          end
+        end
+
+        attr_reader :major, :minor
+
+        def initialize(major, minor)
+          @major = major
+          @minor = minor
+        end
+
+        def ==(other) # :nodoc:
+          other.is_a?(self.class) &&
+            @major == other.major &&
+            @minor == other.minor
+        end
+
+        def to_s # :nodoc:
+          "#{major}.#{minor}"
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/openapi.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'openapi/version'
+require_relative 'openapi/callback'
+require_relative 'openapi/contact'
+require_relative 'openapi/license'
+require_relative 'openapi/info'
+require_relative 'openapi/external_documentation'
+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'

data/lib/jsapi/meta/operation.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    class Operation < Base
+      ##
+      # :attr: callbacks
+      # The optional callbacks. Applies to \OpenAPI 3.x.
+      attribute :callbacks, { String => OpenAPI::Callback }
+
+      ##
+      # :attr: consumed_mime_types
+      # The MIME types consumed by the operation.
+      # Applies to \OpenAPI 2.0 only.
+      attribute :consumed_mime_types, [String]
+
+      alias :consumes :consumed_mime_types
+      alias :consumes= :consumed_mime_types=
+      alias :add_consumes :add_consumed_mime_type
+
+      ##
+      # :attr: deprecated
+      # Specifies whether or not the operation is deprecated.
+      attribute :deprecated, values: [true, false]
+
+      ##
+      # :attr: description
+      # The optional description of the operation.
+      attribute :description, String
+
+      ##
+      # :attr: external_docs
+      # The optional OpenAPI::ExternalDocumentation object.
+      attribute :external_docs, OpenAPI::ExternalDocumentation
+
+      ##
+      # :attr: method
+      # The HTTP verb of the operation. Possible values are:
+      #
+      # - <code>"delete"</code>
+      # - <code>"get"</code>
+      # - <code>"head"</code>
+      # - <code>"options"</code>
+      # - <code>"patch"</code>
+      # - <code>"post"</code>
+      # - <code>"put"</code>
+      #
+      # The default HTTP verb is <code>"get"</code>.
+      attribute :method,
+                values: %w[delete get head options patch post put],
+                default: 'get'
+
+      ##
+      # :attr: model
+      # The model class to access top-level parameters by. The default
+      # model class is Model::Base.
+      attribute :model, Class, default: Model::Base
+
+      ##
+      # :attr_reader: name
+      # The name of the operation.
+      attribute :name, writer: false
+
+      ##
+      # :attr: parameters
+      # The parameters of the operation.
+      attribute :parameters, { String => Parameter },
+                default: {},
+                writer: false
+
+      ##
+      # :attr: path
+      # The relative path of the operation.
+      attribute :path, String
+
+      ##
+      # :attr: consumed_mime_types
+      # The MIME types produced by the operation.
+      # Applies to \OpenAPI 2.0 only.
+      attribute :produced_mime_types, [String]
+
+      alias :produces :produced_mime_types
+      alias :produces= :produced_mime_types=
+      alias :add_produces :add_produced_mime_type
+
+      ##
+      # :attr: request_body
+      # The optional request body of the operation.
+      attribute :request_body, RequestBody
+
+      ##
+      # :attr: responses
+      # The responses of the operation.
+      attribute :responses, { String => Response },
+                default: {},
+                default_key: 'default'
+
+      ##
+      # :attr: schemes
+      # The transfer protocols supported by the operation. Possible
+      # values are:
+      #
+      # - <code>"http"</code>
+      # - <code>"https"</code>
+      # - <code>"ws"</code>
+      # - <code>"wss"</code>
+      #
+      # Applies to \OpenAPI 2.0 only.
+      attribute :schemes, [String], values: %w[http https ws wss]
+
+      ##
+      # :attr: security_requirements
+      # The OpenAPI::SecurityRequirement objects.
+      attribute :security_requirements, [OpenAPI::SecurityRequirement]
+
+      alias add_security add_security_requirement
+
+      ##
+      # :attr: servers
+      # The OpenAPI::Server objects. Applies to \OpenAPI 3.x.
+      attribute :servers, [OpenAPI::Server]
+
+      ##
+      # :attr: summary
+      # The optional summary of the operation.
+      attribute :summary, String
+
+      ##
+      # :attr: tags
+      # The tags used to group operations in an \OpenAPI document.
+      attribute :tags, [String]
+
+      def initialize(name = nil, keywords = {})
+        @name = name&.to_s
+        super(keywords)
+      end
+
+      def add_parameter(name, keywords = {}) # :nodoc:
+        (@parameters ||= {})[name.to_s] = Parameter.new(name, keywords)
+      end
+
+      # Returns a hash representing the \OpenAPI operation object.
+      def to_openapi(version, definitions)
+        version = OpenAPI::Version.from(version)
+        {
+          operationId: name,
+          tags: tags,
+          summary: summary,
+          description: description,
+          externalDocs: external_docs&.to_openapi,
+          deprecated: deprecated?.presence,
+          security: security_requirements&.map(&:to_openapi)
+        }.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
+            hash[:schemes] = schemes if schemes
+          elsif servers
+            hash[:servers] = servers.map(&:to_openapi)
+          end
+          # Parameters (and request body)
+          hash[:parameters] = parameters.values.flat_map do |parameter|
+            parameter.to_openapi(version, definitions)
+          end
+          if request_body
+            if version.major == 2
+              hash[:parameters] << request_body.resolve(definitions).to_openapi_parameter
+            else
+              hash[:request_body] = request_body.to_openapi(version)
+            end
+          end
+          # Responses
+          hash[:responses] = responses.transform_values do |response|
+            response.to_openapi(version, definitions)
+          end
+          # Callbacks
+          if callbacks && version.major > 2
+            hash[:callbacks] = callbacks.transform_values do |callback|
+              callback.to_openapi(version, definitions)
+            end
+          end
+        end.compact
+      end
+    end
+  end
+end

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

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Parameter
+      class Model < Base
+        ##
+        # :attr: deprecated
+        # Specifies whether or not the parameter is deprecated.
+        attribute :deprecated, values: [true, false]
+
+        ##
+        # :attr: description
+        # The optional description of the parameter.
+        attribute :description, String
+
+        ##
+        # :attr_reader: examples
+        # The optional examples.
+        attribute :examples, { String => Example }, default_key: 'default'
+
+        ##
+        # :attr: in
+        # The location of the parameter. Possible values are:
+        #
+        # - <code>"path"</code>
+        # - <code>"query"</code>
+        #
+        # The default location is <code>"query"</code>.
+        attribute :in, String, values: %w[path query], default: 'query'
+
+        ##
+        # :attr_reader: name
+        # The name of the parameter.
+        attribute :name, writer: false
+
+        ##
+        # :attr_reader: schema
+        # The Schema of the parameter.
+        attribute :schema, writer: false
+
+        delegate_missing_to :schema
+
+        # Creates a new parameter.
+        #
+        # Raises an +ArgumentError+ if +name+ is blank.
+        def initialize(name, keywords = {})
+          raise ArgumentError, "parameter name can't be blank" if name.blank?
+
+          keywords = keywords.dup
+          super(keywords.extract!(:deprecated, :description, :examples, :in))
+
+          add_example(value: keywords.delete(:example)) if keywords.key?(:example)
+
+          @name = name.to_s
+          @schema = Schema.new(keywords)
+        end
+
+        # Returns true if empty values are allowed as specified by \OpenAPI,
+        # false otherwise.
+        def allow_empty_value?
+          schema.existence <= Existence::ALLOW_EMPTY && self.in != 'path'
+        end
+
+        # Returns true if it is required as specified by \JSON \Schema,
+        # false otherwise.
+        def required?
+          schema.existence > Existence::ALLOW_OMITTED || self.in == 'path'
+        end
+
+        # Returns an array of hashes representing the \OpenAPI parameter objects.
+        def to_openapi(version, definitions)
+          version = OpenAPI::Version.from(version)
+          schema = self.schema.resolve(definitions)
+
+          if schema.object?
+            explode_object_parameter(
+              name,
+              schema,
+              version,
+              definitions,
+              required: required?,
+              deprecated: deprecated?
+            )
+          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
+            ]
+          end
+        end
+
+        private
+
+        def explode_object_parameter(name, schema, version, definitions, **options)
+          schema.resolve_properties(:read, definitions).values.flat_map do |property|
+            property_schema = property.schema.resolve(definitions)
+            parameter_name = "#{name}[#{property.name}]"
+
+            required = (property.required? && options[:required]).presence
+            deprecated = (property.deprecated? || options[:deprecated]).presence
+
+            if property_schema.object?
+              explode_object_parameter(
+                parameter_name,
+                property_schema,
+                version,
+                definitions,
+                required: required,
+                deprecated: deprecated
+              )
+            else
+              parameter_name = "#{parameter_name}[]" if property_schema.array?
+              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
+              ]
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Parameter
+      class Reference < BaseReference
+        # Returns an array of hashes. Each element 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)
+          version = OpenAPI::Version.from(version)
+          parameter = resolve(definitions)
+
+          if parameter.schema.resolve(definitions).object?
+            # Explode referred parameter
+            parameter.to_openapi(version, definitions)
+          else
+            # Return an array containing the reference object
+            path = version.major == 2 ? 'parameters' : 'components/parameters'
+
+            [{ '$ref': "#/#{path}/#{ref}" }]
+          end
+        end
+      end
+    end
+  end
+end