jsapi 0.1.1

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

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

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      # Represents a contact object.
+      class Contact < Base
+        ##
+        # :attr: email
+        # The email address of the contact.
+        attribute :email, String
+
+        ##
+        # :attr: name
+        # The name of the contact.
+        attribute :name, String
+
+        ##
+        # :attr: url
+        # The URL of the contact.
+        attribute :url, String
+
+        # Returns a hash representing the contact object.
+        def to_openapi(*)
+          {
+            name: name,
+            url: url,
+            email: email
+          }.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      # Represents an external documentation object.
+      class ExternalDocumentation < Base
+        ##
+        # :attr: description
+        # The optional description of the external documentation.
+        attribute :description, String
+
+        ##
+        # :attr: url
+        # The URL of the external documentation.
+        attribute :url, String
+
+        # Returns a hash representing the external documentation object.
+        def to_openapi(*)
+          {
+            url: url,
+            description: description
+          }.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      # Represents an info object.
+      class Info < Base
+        ##
+        # :attr: contact
+        # The optional Contact object.
+        attribute :contact, Contact
+
+        ##
+        # :attr: description
+        # The optional description of the API.
+        attribute :description, String
+
+        ##
+        # :attr: license
+        # The optional License object.
+        attribute :license, License
+
+        ##
+        # :attr: terms_of_service
+        # The optional 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 info object.
+        def to_openapi(*)
+          {
+            title: title,
+            version: version,
+            description: description,
+            termsOfService: terms_of_service,
+            contact: contact&.to_openapi,
+            license: license&.to_openapi
+          }.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      # Represents a license object.
+      class License < Base
+        ##
+        # :attr: name
+        # The name of the license.
+        attribute :name, String
+
+        ##
+        # :attr: url
+        # The optional URL of the license.
+        attribute :url, String
+
+        # Returns a hash representing the license object.
+        def to_openapi(*)
+          {
+            name: name,
+            url: url
+          }.compact
+        end
+      end
+    end
+  end
+end

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

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

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

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

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

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

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      # Represents an OAuth flow object.
+      class OAuthFlow < Base
+        class Scope < Base
+          ##
+          # :attr: description
+          # The optional 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 }, default: {}
+
+        ##
+        # :attr: token_url
+        # The token URL to be used for the flow.
+        attribute :token_url, String
+
+        # Returns a hash representing the OAuth flow object.
+        def to_openapi(version)
+          {
+            authorizationUrl: authorization_url,
+            tokenUrl: token_url,
+            refreshUrl: (refresh_url if version.major > 2),
+            scopes: scopes.transform_values(&:description)
+          }.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      # Represents an \OpenAPI object.
+      class Root < Base
+        ##
+        # :attr: callbacks
+        # The reusable Callback objects. Applies to \OpenAPI 3.x.
+        attribute :callbacks, { String => Callback }
+
+        ##
+        # :attr: base_path
+        # The base path of the API. Applies to \OpenAPI 2.0.
+        attribute :base_path, String
+
+        ##
+        # :attr: consumes
+        # The MIME types the API can consume. Applies to \OpenAPI 2.0.
+        attribute :consumed_mime_types, [String]
+
+        alias :consumes :consumed_mime_types
+        alias :consumes= :consumed_mime_types=
+        alias :add_consumes :add_consumed_mime_type
+
+        ##
+        # :attr: external_docs
+        # The optional ExternalDocumentation object.
+        attribute :external_docs, ExternalDocumentation
+
+        ##
+        # :attr: host
+        # The host serving the API. Applies to \OpenAPI 2.0.
+        attribute :host, String
+
+        ##
+        # :attr: info
+        # The Info object.
+        attribute :info, Info
+
+        ##
+        # :attr: links
+        # The reusable Link objects. Applies to \OpenAPI 3.x.
+        attribute :links, { String => Link }
+
+        ##
+        # :attr: produces
+        # The MIME types the API can produce. Applies to \OpenAPI 2.0.
+        attribute :produced_mime_types, [String]
+
+        alias :produces :produced_mime_types
+        alias :produces= :produced_mime_types=
+        alias :add_produces :add_produced_mime_type
+
+        ##
+        # :attr: schemes
+        # The array of transfer protocols supported by the API. Possible
+        # values are:
+        #
+        # - <code>"http"</code>
+        # - <code>"https"</code>
+        # - <code>"ws"</code>
+        # - <code>"wss"</code>
+        #
+        # Applies to \OpenAPI 2.0.
+        attribute :schemes, [String], values: %w[http https ws wss]
+
+        ##
+        # :attr: security_requirements
+        # The array of SecurityRequirement objects.
+        attribute :security_requirements, [SecurityRequirement]
+
+        alias add_security add_security_requirement
+
+        ##
+        # :attr_reader: security_schemes
+        # The security schemes.
+        attribute :security_schemes, { String => SecurityScheme }
+
+        ##
+        # :attr: servers
+        # The array of Server objects. Applies to \OpenAPI 3.x.
+        attribute :servers, [Server]
+
+        ##
+        # :attr: tags
+        # The array of Tag objects.
+        attribute :tags, [Tag]
+
+        # Returns a hash representing the \OpenAPI object.
+        def to_openapi(version, definitions)
+          version = Version.from(version)
+          security_schemes =
+            self.security_schemes&.transform_values do |value|
+              value.to_openapi(version)
+            end
+
+          if version.major == 2
+            {
+              swagger: '2.0',
+              info: info&.to_openapi,
+              host: host,
+              basePath: base_path,
+              schemes: schemes,
+              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
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      module SecurityScheme
+        # Represents a security scheme based on an API key.
+        class APIKey < Base
+          ##
+          # :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 security scheme object.
+          def to_openapi(*)
+            {
+              type: 'apiKey',
+              name: name,
+              in: self.in,
+              description: description
+            }.compact
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      module SecurityScheme
+        module HTTP
+          # Represents a security scheme based on \HTTP basic authentication.
+          class Basic < Base
+            # Returns a hash representing the 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
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      module SecurityScheme
+        module HTTP
+          # Represents 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
+            ##
+            # :attr: bearer_format
+            # The optional format of the bearer token.
+            attribute :bearer_format, String
+
+            # Returns a hash representing the 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
+
+              {
+                type: 'http',
+                scheme: 'bearer',
+                bearerFormat: bearer_format,
+                description: description
+              }.compact
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      module SecurityScheme
+        module HTTP
+          # Represents 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
+            ##
+            # :attr: scheme
+            # The mandatory \HTTP authentication scheme.
+            attribute :scheme, String
+
+            # Returns a hash representing the 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
+
+              {
+                type: 'http',
+                scheme: scheme,
+                description: description
+              }.compact
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'http/basic'
+require_relative 'http/bearer'
+require_relative 'http/other'
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      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
+end