jsapi 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78a92c9f73f4a39ede65ad5b0b5646db67dc8b9e2b3ca444b6de32fdb75e349a
-  data.tar.gz: e235535541854c172f578cce7cf112ceebe880971643cb33125a76cc61bbd88a
+  metadata.gz: d672ecea7da1c27309fe576ceacc537286529da833a37726f8e34299b33d7d48
+  data.tar.gz: 9d2d663c47dc498def2c9ce60b73029bfba52a0a2b15690e4a41b4a0bed3d70a
 SHA512:
-  metadata.gz: 7c139744bacb90f772bb40779a8d149daf025dd838ffc3268c35640dfe18da1934e62ffd2e319658478ef5c4d54a4f630ed76eabf60a22df641f1ce7da218150
-  data.tar.gz: b9e72517dea9061eaa23b5ff5631745a18769614c04d2a91ae97db2e715c30504bc5b849fdcaa89384f7fb2618e5ea639601f637b9583b5fec219bd053006f08
+  metadata.gz: 241798754adbc58ad39ecf1d238977ec5b7bba2f557b2d4fd5190eb9cc4b14db5afeeb61cc48a6e1435be03178b95e0728deaa4d5afa3b58758becc765ee9105
+  data.tar.gz: b8823805ad8cf8d09dd72a8ef930086bcb3f4554ad9f868f7a6554062f263bd450fe14f01f21fbfb58b47577681d86a8fd9e5655a0ed522833e223c7478a278e

data/lib/jsapi/controller/methods.rb

@@ -130,6 +130,15 @@ module Jsapi
             response = operation.response(status)&.resolve(definitions)
             raise e if response.nil?
 
+            # Call on_rescue callbacks
+            definitions.on_rescue_callbacks.each do |callback|
+              if callback.respond_to?(:call)
+                callback.call(e)
+              else
+                send(callback, e)
+              end
+            end
+
             ErrorResult.new(e, status: status)
           end
           render(json: Response.new(result, response, definitions), status: status)

data/lib/jsapi/controller/parameters.rb

@@ -45,7 +45,7 @@ module Jsapi
         [
           validate_attributes(errors),
           !@strong || validate_parameters(
-            @params.except(:controller, :action),
+            @params.except(:controller, :action, :format),
             attributes,
             errors
           )

data/lib/jsapi/dsl/class_methods.rb

@@ -15,6 +15,11 @@ module Jsapi
         api_definitions { include(*klasses) }
       end
 
+      # Registers a callback to be called when rescuing an exception.
+      def api_on_rescue(method = nil, &block)
+        api_definitions { on_rescue(method, &block) }
+      end
+
       # Defines an operation.
       #
       #   api_operation 'foo', path: '/foo' do

data/lib/jsapi/dsl/definitions.rb

@@ -12,6 +12,13 @@ module Jsapi
         end
       end
 
+      # Registers a callback to be called when rescuing an exception.
+      def on_rescue(method = nil, &block)
+        _define('on_rescue') do
+          _meta_model.add_on_rescue(method || block)
+        end
+      end
+
       # Defines the root of an \OpenAPI document.
       #
       #   openapi do

data/lib/jsapi/meta/definitions.rb

@@ -3,10 +3,11 @@
 module Jsapi
   module Meta
     class Definitions
-      attr_reader :examples, :openapi_root, :operations, :parameters,
+      attr_reader :callbacks, :examples, :openapi_root, :operations, :parameters,
                   :request_bodies, :rescue_handlers, :responses, :schemas
 
       def initialize(owner = nil)
+        @callbacks = { on_rescue: [] }
         @owner = owner
         @examples = {}
         @operations = {}
@@ -19,7 +20,11 @@ module Jsapi
       end
 
       def add_example(name, keywords = {})
-        @examples[name.to_s] = Example.new(keywords)
+        @examples[name.to_s] = OpenAPI::Example.new(keywords)
+      end
+
+      def add_on_rescue(method_or_proc)
+        @callbacks[:on_rescue] << method_or_proc
       end
 
       def add_operation(name = nil, keywords = {})
@@ -86,6 +91,12 @@ module Jsapi
         end
       end
 
+      def on_rescue_callbacks
+        @self_and_included.flat_map do |definitions|
+          definitions.callbacks[:on_rescue]
+        end
+      end
+
       # Returns a hash representing the OpenAPI document for +version+.
       # Raises an +ArgumentError+ if +version+ is not supported.
       def openapi_document(version = nil)
@@ -101,15 +112,13 @@ module Jsapi
               responses: openapi_responses(version)
             )
           else
-            h.deep_merge!(
-              components: {
-                schemas: openapi_schemas(version),
-                parameters: openapi_parameters(version),
-                requestBodies: openapi_request_bodies(version),
-                responses: openapi_responses(version),
-                examples: openapi_examples
-              }.compact.presence
-            )
+            h[:components] = (h[:components] || {}).merge(
+              schemas: openapi_schemas(version),
+              parameters: openapi_parameters(version),
+              requestBodies: openapi_request_bodies(version),
+              responses: openapi_responses(version),
+              examples: openapi_examples
+            ).compact.presence
           end
         end.compact
       end

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

@@ -23,7 +23,7 @@ module Jsapi
             @operations&.[](expression&.to_s)
           end
 
-          # Returns a hash representing the callback object.
+          # Returns a hash representing the \OpenAPI callback object.
           def to_openapi(version, definitions)
             operations.transform_values do |operation|
               { operation.method => operation.to_openapi(version, definitions) }

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

@@ -22,7 +22,7 @@ module Jsapi
         # The URL of the contact.
         attribute :url, String
 
-        # Returns a hash representing the contact object.
+        # Returns a hash representing the \OpenAPI contact object.
         def to_openapi(*)
           with_openapi_extensions(name: name, url: url, email: email)
         end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      module Example
+        class Model < Base
+          include Extensions
+
+          ##
+          # :attr: description
+          # The optional description of the example.
+          attribute :description, String
+
+          ##
+          # :attr: external
+          # If true, +value+ is interpreted as a URI pointing to an external sample value.
+          attribute :external, values: [true, false]
+
+          ##
+          # :attr: summary
+          # The optional summary of the example.
+          attribute :summary, String
+
+          ##
+          # :attr: value
+          # The sample value.
+          attribute :value
+
+          # Returns a hash representing the \OpenAPI example object.
+          def to_openapi(*)
+            with_openapi_extensions(summary: summary, description: description).tap do |hash|
+              if external?
+                hash[:external_value] = value
+              else
+                hash[:value] = value
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'example/model'
+require_relative 'example/reference'
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      module Example
+        class << self
+          # Creates a new example 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/external_documentation.rb

@@ -17,7 +17,7 @@ module Jsapi
         # The URL of the external documentation.
         attribute :url, String
 
-        # Returns a hash representing the external documentation object.
+        # Returns a hash representing the \OpenAPI external documentation object.
         def to_openapi(*)
           with_openapi_extensions(url: url, description: description)
         end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      module Header
+        class Model < Base
+          include Extensions
+
+          ##
+          # :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, writer: false
+
+          delegate_missing_to :schema
+
+          def initialize(keywords = {})
+            keywords = keywords.dup
+            super(keywords.extract!(:deprecated, :description, :examples))
+
+            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(
+                  description: description
+                )
+              else
+                {
+                  description: description,
+                  deprecated: deprecated?.presence,
+                  schema: schema.to_openapi(version),
+                  examples: examples&.transform_values(&:to_openapi)
+                }
+              end
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'header/model'
+require_relative 'header/reference'
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      module Header
+        class << self
+          # Creates a header 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/info.rb

@@ -37,7 +37,7 @@ module Jsapi
         # The version of the API.
         attribute :version, String
 
-        # Returns a hash representing the info object.
+        # Returns a hash representing the \OpenAPI info object.
         def to_openapi(*)
           with_openapi_extensions(
             title: title,

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

@@ -17,7 +17,7 @@ module Jsapi
         # The optional URL of the license.
         attribute :url, String
 
-        # Returns a hash representing the license object.
+        # Returns a hash representing the \OpenAPI license object.
         def to_openapi(*)
           with_openapi_extensions(name: name, url: url)
         end

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

@@ -33,7 +33,7 @@ module Jsapi
           # The optional Server object.
           attribute :server, Server
 
-          # Returns a hash representing the link object.
+          # Returns a hash representing the \OpenAPI link object.
           def to_openapi(*)
             with_openapi_extensions(
               operationId: operation_id,

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

@@ -37,7 +37,7 @@ module Jsapi
         # The token URL to be used for the flow.
         attribute :token_url, String
 
-        # Returns a hash representing the OAuth flow object.
+        # Returns a hash representing the \OpenAPI OAuth flow object.
         def to_openapi(version)
           with_openapi_extensions(
             authorizationUrl: authorization_url,

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

@@ -31,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.
@@ -122,6 +127,9 @@ module Jsapi
                   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,

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

@@ -24,7 +24,7 @@ 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',

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

@@ -9,7 +9,7 @@ module Jsapi
           class Basic < Base
             include Extensions
 
-            # Returns a hash representing the security scheme object.
+            # Returns a hash representing the \OpenAPI security scheme object.
             def to_openapi(version)
               version = OpenAPI::Version.from(version)
 

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

@@ -18,7 +18,7 @@ module Jsapi
             # 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)

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

@@ -19,7 +19,7 @@ module Jsapi
             # 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)

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

@@ -21,7 +21,7 @@ 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)
 

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

@@ -15,7 +15,7 @@ module Jsapi
           # :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)

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

@@ -22,7 +22,7 @@ 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,

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

@@ -22,7 +22,7 @@ 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,

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

@@ -22,7 +22,7 @@ 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,

data/lib/jsapi/meta/openapi.rb

@@ -6,7 +6,9 @@ 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/parameter/model.rb

@@ -19,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

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

@@ -14,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

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

@@ -14,7 +14,12 @@ module Jsapi
         ##
         # :attr: examples
         # The optional examples.
-        attribute :examples, { String => Example }, default_key: 'default'
+        attribute :examples, { String => OpenAPI::Example }, default_key: 'default'
+
+        ##
+        # :attr: headers
+        # The response headers.
+        attribute :headers, { String => OpenAPI::Header }
 
         ##
         # :attr: links
@@ -52,6 +57,9 @@ module Jsapi
               {
                 description: description,
                 schema: schema.to_openapi(version),
+                headers: headers&.transform_values do |header|
+                  header.to_openapi(version) unless header.reference?
+                end&.compact,
                 examples: (
                   if (example = examples&.values&.first).present?
                     { 'application/json' => example.resolve(definitions).value }
@@ -67,6 +75,7 @@ module Jsapi
                     examples: examples&.transform_values(&:to_openapi)
                   }.compact
                 },
+                headers: headers&.transform_values { |header| header.to_openapi(version) },
                 links: links&.transform_values(&:to_openapi)
               }
             end

data/lib/jsapi/meta.rb

@@ -6,7 +6,6 @@ require_relative 'meta/attributes'
 require_relative 'meta/base'
 require_relative 'meta/base_reference'
 require_relative 'meta/openapi'
-require_relative 'meta/example'
 require_relative 'meta/existence'
 require_relative 'meta/property'
 require_relative 'meta/schema'

data/lib/jsapi/version.rb

@@ -5,6 +5,6 @@ module Jsapi
     # NOTE: See https://bundler.io/guides/creating_gem.html
 
     # The current GEM version.
-    VERSION = '0.3.0'
+    VERSION = '0.4.1'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jsapi
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Denis Göller
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-07-14 00:00:00.000000000 Z
+date: 2024-08-21 00:00:00.000000000 Z
 dependencies: []
 description: Jsapi can be used to read requests, produce responses and create OpenAPI
   documents
@@ -56,9 +56,6 @@ files:
 - lib/jsapi/meta/base.rb
 - lib/jsapi/meta/base_reference.rb
 - lib/jsapi/meta/definitions.rb
-- lib/jsapi/meta/example.rb
-- lib/jsapi/meta/example/model.rb
-- lib/jsapi/meta/example/reference.rb
 - lib/jsapi/meta/existence.rb
 - lib/jsapi/meta/invalid_argument_error.rb
 - lib/jsapi/meta/openapi.rb
@@ -66,8 +63,14 @@ files:
 - lib/jsapi/meta/openapi/callback/model.rb
 - lib/jsapi/meta/openapi/callback/reference.rb
 - lib/jsapi/meta/openapi/contact.rb
+- lib/jsapi/meta/openapi/example.rb
+- lib/jsapi/meta/openapi/example/model.rb
+- lib/jsapi/meta/openapi/example/reference.rb
 - lib/jsapi/meta/openapi/extensions.rb
 - lib/jsapi/meta/openapi/external_documentation.rb
+- lib/jsapi/meta/openapi/header.rb
+- lib/jsapi/meta/openapi/header/model.rb
+- lib/jsapi/meta/openapi/header/reference.rb
 - lib/jsapi/meta/openapi/info.rb
 - lib/jsapi/meta/openapi/license.rb
 - lib/jsapi/meta/openapi/link.rb

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

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-module Jsapi
-  module Meta
-    module Example
-      class Model < Base
-        include OpenAPI::Extensions
-
-        ##
-        # :attr: description
-        # The optional description of the example.
-        attribute :description, String
-
-        ##
-        # :attr: external
-        # If true, +value+ is interpreted as a URI pointing to an external sample value.
-        attribute :external, values: [true, false]
-
-        ##
-        # :attr: summary
-        # The optional summary of the example.
-        attribute :summary, String
-
-        ##
-        # :attr: value
-        # The sample value.
-        attribute :value
-
-        # Returns a hash representing the \OpenAPI example object.
-        def to_openapi(*)
-          with_openapi_extensions(summary: summary, description: description).tap do |hash|
-            if external?
-              hash[:external_value] = value
-            else
-              hash[:value] = value
-            end
-          end
-        end
-      end
-    end
-  end
-end

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

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

data/lib/jsapi/meta/example.rb

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