yori 0.1.0

data/lib/yori/schema/v3/operation.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'yori/schema/v3/external_documentation'
+require 'yori/schema/v3/parameter'
+require 'yori/schema/v3/request_body'
+require 'yori/schema/v3/responses'
+require 'yori/schema/v3/callback'
+require 'yori/schema/v3/security_requirement'
+require 'yori/schema/v3/server'
+
+module Yori
+  module Schema
+    module V3
+      # Operaion: Describes a single API operation on a path.
+      class Operation < Yori::SchemaBase
+        # @!method tags
+        #   A list of tags for API documentation control.
+        #   Tags can be used for logical grouping of operations by resources or any other qualifier.
+        # @!method summary A short summary of what the operation does.
+        # @!method description
+        #   A verbose explanation of the operation behavior.
+        #   CommonMark syntax MAY be used for rich text representation.
+        # @!method operationId
+        #   Unique string used to identify the operation. The id MUST be unique among all operations described in the API.
+        #   Tools and libraries MAY use the operationId to uniquely identify an operation,
+        #   therefore, it is RECOMMENDED to follow common programming naming conventions.
+        # @!method deprecated
+        #   Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation.
+        #   Default value is false.
+        fields :tags, :summary, :description, :operationId, :deprecated
+        # @!method externalDocs
+        #   Additional external documentation for this operation.
+        field_block :externalDocs, Yori::Schema::V3::ExternalDocumentation
+        # @!method parameters
+        #   A list of parameters that are applicable for this operation.
+        #   If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
+        #   The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a name and location.
+        #   The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's components/parameters.
+        array_field_block :parameters, :parameter, Yori::Schema::V3::Parameter
+        # @!method requestBody
+        #   The request body applicable for this operation.
+        #   The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly defined semantics for request bodies.
+        #   In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
+        field_block :requestBody, Yori::Schema::V3::RequestBody
+        # @!method responses
+        #   REQUIRED. The list of possible responses as they are returned from executing this operation.
+        field_block :responses, Yori::Schema::V3::Responses
+        # @!method callbacks
+        #   A map of possible out-of band callbacks related to the parent operation.
+        #   The key is a unique identifier for the Callback Object.
+        #   Each value in the map is a Callback Object that describes a request that may be initiated by the API provider and the expected responses.
+        #   The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation.
+        hash_field_block :callbacks, :callback, Yori::Schema::V3::Callback
+        # @!method security
+        #   A declaration of which security mechanisms can be used for this operation.
+        #   The list of values includes alternative security requirement objects that can be used.
+        #   Only one of the security requirement objects need to be satisfied to authorize a request.
+        #   This definition overrides any declared top-level security.
+        #   To remove a top-level security declaration, an empty array can be used.
+        array_field_block :security, :schemes, Yori::Schema::V3::SecurityRequirement
+        # @!method servers
+        #   An alternative server array to service this operation.
+        #   If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by this value.
+        array_field_block :servers, :server, Yori::Schema::V3::Server
+
+        def validate!
+          validate_require_fields!('responses')
+        end
+      end
+    end
+  end
+end

data/lib/yori/schema/v3/parameter.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'yori/schema/v3/schema'
+require 'yori/schema/v3/example'
+require 'yori/schema/v3/media_type'
+
+module Yori
+  module Schema
+    module V3
+      # Parameter: Describes a single operation parameter.
+      class Parameter < Yori::SchemaBase
+        fields :name, :description, :required, :deprecated, :allowEmptyValue
+
+        def in_query
+          self['in'] = 'query'
+        end
+
+        def in_header
+          self['in'] = 'header'
+        end
+
+        def in_path
+          self['in'] = 'path'
+        end
+
+        def in_cookie
+          self['in'] = 'cookie'
+        end
+
+        fields :style, :explode, :allowReserved
+        field_block :schema, Yori::Schema::V3::Schema
+
+        def example_any(value)
+          self['example'] = value
+        end
+
+        hash_field_block :examples, :example, Yori::Schema::V3::Example
+        hash_field_block :content, :content_type, Yori::Schema::V3::MediaType
+
+        def validate!
+          validate_require_fields!('name', 'in')
+          validate_in!
+          validate_schema_or_content!
+        end
+
+        def validate_in!
+          validate_limit_field_values!('in', 'query', 'header', 'path', 'cookie')
+          in_value = self['in']
+
+          case in_value
+          when 'path'
+            validate_require_fields!('required')
+            validate_limit_field_values!('required', true)
+          end
+        end
+
+        def validate_schema_or_content!
+          validate_mutually_exclusive_fields!('schema', 'content')
+        end
+      end
+    end
+  end
+end

data/lib/yori/schema/v3/path_item.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'yori/schema/v3/operation'
+require 'yori/schema/v3/server'
+require 'yori/schema/v3/parameter'
+
+module Yori
+  module Schema
+    module V3
+      # PathItem
+      #   Describes the operations available on a single path.
+      #   A Path Item MAY be empty, due to ACL constraints.
+      #   The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available.
+      class PathItem < Yori::SchemaBase
+        # @!method summary
+        #   An optional, string summary, intended to apply to all operations in this path.
+        # @!method description
+        #   An optional, string description, intended to apply to all operations in this path.
+        #   CommonMark syntax MAY be used for rich text representation.
+        fields :summary, :description
+
+        # @!method get A definition of a GET operation on this path.
+        # @!method put A definition of a PUT operation on this path.
+        # @!method post A definition of a POST operation on this path.
+        # @!method delete A definition of a DELETE operation on this path.
+        # @!method options A definition of a OPTIONS operation on this path.
+        # @!method head A definition of a HEAD operation on this path.
+        # @!method patch A definition of a PATH operation on this path.
+        # @!method trace A definition of a TRACE operation on this path.
+        %i[get put post delete options head patch trace].each do |method|
+          field_block method, Yori::Schema::V3::Operation
+        end
+
+        # @!method servers
+        #   An alternative server array to service all operations in this path.
+        array_field_block :servers, :server, Yori::Schema::V3::Server
+
+        # @!method parameters
+        #   A list of parameters that are applicable for all the operations described under this path.
+        #   These parameters can be overridden at the operation level, but cannot be removed there.
+        #   The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a name and location.
+        #   The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's components/parameters.
+        array_field_block :parameters, :parameter, Yori::Schema::V3::Parameter
+      end
+    end
+  end
+end

data/lib/yori/schema/v3/paths.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'yori/schema/v3/path_item'
+
+module Yori
+  module Schema
+    module V3
+      # Paths
+      #   Holds the relative paths to the individual endpoints and their operations.
+      #   The path is appended to the URL from the Server Object in order to construct the full URL.
+      #   The Paths MAY be empty, due to ACL constraints.
+      class Paths < Yori::SchemaBase
+        # @!method path
+        #   A relative path to an individual endpoint. The field name MUST begin with a slash.
+        #   The path is appended (no relative URL resolution) to the expanded URL from the Server Object's url field in order to construct the full URL.
+        #   Path templating is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts.
+        #   Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical.
+        #   In case of ambiguous matching, it's up to the tooling to decide which one to use.
+        def path(path_temp, value = nil, &block)
+          path_temp = '/' + path_temp unless path_temp.start_with?('/')
+          self[path_temp] = self.class.eval_input!(Yori::Schema::V3::PathItem, id, value, &block)
+        end
+
+        def merge_registered!
+          self.class.registered_path[id]&.each do |_path, block|
+            instance_eval(&block)
+          end
+        end
+
+        class << self
+          def registered_path
+            @registered_path ||= {}
+          end
+
+          def register_path(id, path, value = nil, &block)
+            @registered_path ||= {}
+            @registered_path[id] ||= {}
+            @registered_path[id][path] = proc { path(path, value, &block) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yori/schema/v3/request_body.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'yori/schema/v3/media_type'
+
+module Yori
+  module Schema
+    module V3
+      # RequestBody: Describes a single request body.
+      class RequestBody < Yori::SchemaBase
+        # @!method description
+        #   A brief description of the request body. This could contain examples of use.
+        #   CommonMark syntax MAY be used for rich text representation.
+        # @!method required
+        #   Determines if the request body is required in the request. Defaults to false.
+        fields :description, :required
+        # @!method content
+        #   REQUIRED. The content of the request body. The key is a media type or media type range and the value describes it.
+        #   For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+        hash_field_block :content, :content_type, Yori::Schema::V3::MediaType
+
+        def validate!
+          validate_require_fields!('content')
+        end
+      end
+    end
+  end
+end

data/lib/yori/schema/v3/response.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'yori/schema/v3/header'
+require 'yori/schema/v3/media_type'
+require 'yori/schema/v3/link'
+
+module Yori
+  module Schema
+    module V3
+      # Response: Describes a single response from an API Operation, including design-time, static links to operations based on the response.
+      class Response < Yori::SchemaBase
+        # @!method description
+        #   REQUIRED. A short description of the response. CommonMark syntax MAY be used for rich text representation.
+        fields :description
+        # @!method headers
+        #   Maps a header name to its definition. RFC7230 states header names are case insensitive.
+        #   If a response header is defined with the name "Content-Type", it SHALL be ignored.
+        hash_field_block :headers, :header, Yori::Schema::V3::Header
+        # @!method content
+        #   A map containing descriptions of potential response payloads. The key is a media type or media type range and the value describes it.
+        #   For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+        hash_field_block :content, :content_type, Yori::Schema::V3::MediaType
+        # @!method links
+        #   A map of operations links that can be followed from the response.
+        #   The key of the map is a short name for the link, following the naming constraints of the names for Component Objects.
+        hash_field_block :links, :link, Yori::Schema::V3::Link
+
+        def validate!
+          validate_require_fields!('description')
+        end
+      end
+    end
+  end
+end

data/lib/yori/schema/v3/responses.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'yori/schema/v3/response'
+
+module Yori
+  module Schema
+    module V3
+      # Responses:
+      #   A container for the expected responses of an operation.
+      #   The container maps a HTTP response code to the expected response.
+      #   The documentation is not necessarily expected to cover all possible HTTP response codes because they may not be known in advance.
+      #   However, documentation is expected to cover a successful operation response and any known errors.
+      #   The default MAY be used as a default response object for all HTTP codes that are not covered individually by the specification.
+      #   The Responses Object MUST contain at least one response code, and it SHOULD be the response for a successful operation call.
+      class Responses < Yori::SchemaBase
+        # @!method default
+        #   The documentation of responses other than the ones declared for specific HTTP response codes.
+        #   Use this field to cover undeclared responses. A Reference Object can link to a response that the OpenAPI Object's components/responses section defines.
+        field_block :default, Yori::Schema::V3::Response
+
+        # @!method response
+        #   Any HTTP status code can be used as the property name, but only one property per code, to describe the expected response for that HTTP status code.
+        #   A Reference Object can link to a response that is defined in the OpenAPI Object's components/responses section.
+        #   This field MUST be enclosed in quotation marks (for example, "200") for compatibility between JSON and YAML.
+        #   To define a range of response codes, this field MAY contain the uppercase wildcard character X.
+        #   For example, 2XX represents all response codes between [200-299]. The following range definitions are allowed: 1XX, 2XX, 3XX, 4XX, and 5XX.
+        #   If a response range is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code.
+        def response(status_code, &block)
+          self[status_code.to_s] = self.class.eval_class!(Yori::Schema::V3::Response, id, &block)
+        end
+
+        alias status response
+        alias http_status_code response
+
+        def validate!
+          status_keys = keys.reject { |x| x == 'default' }
+          raise Yori::Errors::InvalidSchemaError, 'The Responses Object MUST contain at least one response code.' if status_keys.empty?
+        end
+      end
+    end
+  end
+end

data/lib/yori/schema/v3/root.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Yori
+  module Schema
+    module V3
+      # Root
+      module Root
+        def self.included(klass)
+          klass.class_eval do
+            class << self
+              def api_docs_factory
+                @_api_docs_factory
+              end
+
+              def api_docs
+                return unless api_docs_factory
+
+                openapi = api_docs_factory.call
+                openapi.to_json
+              end
+
+              def root(id = '', &block)
+                @_api_docs_factory = proc do
+                  Yori::Schema::V3::OpenAPI.new.tap do |openapi|
+                    openapi.id = id
+                    openapi.instance_eval(&block)
+                  end
+                end
+              end
+            end
+          end
+        end
+
+        def api_docs
+          self.class.api_docs
+        end
+      end
+    end
+  end
+end

data/lib/yori/schema/v3/schema.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'yori/schema/v3/discriminator'
+require 'yori/schema/v3/xml'
+require 'yori/schema/v3/external_documentation'
+
+module Yori
+  module Schema
+    module V3
+      # Schema: The Schema Object allows the definition of input and output data types.
+      #   These types can be objects, but also primitives and arrays. This object is an extended subset of the JSON Schema Specification Wright Draft 00.
+      class Schema < SchemaBase
+        fields :title, :type, :description, :format, :default
+        fields :multipleOf, :maximum, :exclusiveMaximum, :minimum, :exclusiveMinimum, :maxLength, :minLength
+        fields :pattern, :maxItems, :minItems, :uniqueItems
+        fields :maxProperties, :minProperties, :required, :enum
+
+        array_field_block :allOf, :allOfItem, Yori::Schema::V3::Schema
+        array_field_block :oneOf, :oneOfItem, Yori::Schema::V3::Schema
+        array_field_block :anyOf, :anyOfItem, Yori::Schema::V3::Schema
+        array_field_block :not, :notItem, Yori::Schema::V3::Schema
+
+        field_block :items, Yori::Schema::V3::Schema
+        hash_field_block :properties, :property, Yori::Schema::V3::Schema
+        field_block :additionalProperties, Yori::Schema::V3::Schema
+
+        fields :nullable, :readOnly, :writeOnly, :deprecated
+        field_block :discriminator, Yori::Schema::V3::Discriminator
+        field_block :xml, Yori::Schema::V3::XML
+        field_block :externalDocs, Yori::Schema::V3::ExternalDocumentation
+        field_block :example, Yori::Schema::Any
+      end
+    end
+  end
+end

data/lib/yori/schema/v3/security_requirement.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Yori
+  module Schema
+    module V3
+      # SecurityRequirement:
+      #   Lists the required security schemes to execute this operation.
+      #   The name used for each property MUST correspond to a security scheme declared in the Security Schemes under the Components Object.
+      class SecurityRequirement < Yori::SchemaBase
+        # @!method scheme
+        #   Each key MUST correspond to a security scheme which is declared in the Security Schemes under the Components Object.
+        #   If the security scheme is of type "oauth2" or "openIdConnect", then the value is a list of scope names required for the execution.
+        #   For other security scheme types, the array MUST be empty.
+        def scheme(key, scopes)
+          self[key.to_s] ||= []
+          self[key.to_s].concat(scopes)
+        end
+
+        # TODO: validate with related SecurityScheme type...
+      end
+    end
+  end
+end

data/lib/yori/schema/v3/security_scheme.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'yori/schema/v3/oauth_flows'
+
+module Yori
+  module Schema
+    module V3
+      # SecurityScheme:
+      #   Defines a security scheme that can be used by the operations.
+      #   Supported schemes are HTTP authentication, an API key (either as a header or as a query parameter),
+      #   OAuth2's common flows (implicit, password, application and access code) as defined in RFC6749, and OpenID Connect Discovery.
+      class SecurityScheme < Yori::SchemaBase
+        # @!method type :Applies To Any;
+        #   REQUIRED. The type of the security scheme.
+        #   Valid values are "apiKey", "http", "oauth2", "openIdConnect"
+        # @!method description :Applies To Any;
+        #   A short description for security scheme. CommonMark syntax MAY be used for rich text representation.
+        # @!method name :Applies To apiKey;
+        #   REQUIRED. The name of the header, query or cookie parameter to be used.
+        fields :type, :description, :name
+
+        # @!method in_query
+        #   Set 'query' value to 'in' field.
+        def in_query
+          self['in'] = 'query'
+        end
+
+        # @!method in_header
+        #   Set 'header' value to 'in' field.
+        def in_header
+          self['in'] = 'header'
+        end
+
+        # @!method in_cookie
+        #   Set 'cookie' value to 'in' field.
+        def in_cookie
+          self['in'] = 'cookie'
+        end
+
+        # @!method scheme :Applies To http;
+        #   REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC7235.
+        # @!method bearerFormat :Applies To http ("bearer");
+        #   A hint to the client to identify how the bearer token is formatted.
+        #   Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.
+        fields :scheme, :bearerFormat
+
+        # @!method flows :Applies To oauth2;
+        #   REQUIRED. An object containing configuration information for the flow types supported.
+        field_block :flows, Yori::Schema::V3::OAuthFlows
+
+        # @!method openIdConnectUrl :Applies To openIdConnect
+        #   REQUIRED. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL.
+        fields :openIdConnectUrl
+
+        def validate!
+          validate_type!
+          case self['type']
+          when 'apiKey'
+            validate_as_api_key!
+          when 'http'
+            validate_as_http!
+          when 'oauth2'
+            validate_as_oauth2!
+          when 'openIdConnect'
+            validate_as_open_id_connect!
+          end
+        end
+
+        def validate_type!
+          validate_require_fields!('type')
+          validate_limit_field_values!('type', 'apiKey', 'http', 'oauth2', 'openIdConnect')
+        end
+
+        def validate_as_api_key!
+          validate_require_fields!('name', 'in')
+          validate_limit_field_values!('in', 'query', 'header', 'cookie')
+        end
+
+        def validate_as_http!
+          validate_require_fields!('scheme')
+        end
+
+        def validate_as_oauth2!
+          validate_require_fields!('flows')
+        end
+
+        def validate_as_open_id_connect!
+          validate_require_fields!('openIdConnectUrl')
+        end
+      end
+    end
+  end
+end