taro 1.4.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d30f413c950e02e52f99ed96d234acdba122c92ec4e39dd2d35e87c899ed8a13
-  data.tar.gz: 5ed455623397ce6fbcb19412710bf98bc7ca2b6898db193a2cf858104a149327
+  metadata.gz: c4f35df13466f65caaf120945539ca21fcd2562dc3e79145817c66f75f58c016
+  data.tar.gz: c3f2af6555b7a3c9f6e81a6ba69f5fceea0663ed6b93c22cfe584f478a2a4b24
 SHA512:
-  metadata.gz: ba99529dd914238371708a80b5f3f6497a4884a042a0e11ec7e9b557107379d0bfa2232b6a71137623658651e5d920f8ad47ab683119ae5ce105261fa627b980
-  data.tar.gz: 26b2652184c485aa7970707373cfe4ebfdecd3141fc7e995066060b5a0a5452b1e749d6e16fdc3d99e34a199434ed9edc7400d89fe8f8ed32df442d764d06175
+  metadata.gz: c3c7de4bb79a0f78f1060ea32bf65e1da9bf597f09790d95f5c0e09a0fdc175de973aebdc28c39a1aa994dbd0fd41e6be3097508ddfad57474ad774603aac933
+  data.tar.gz: aad75b1177ff07d1e95415e720076d85734de7ebd185e2503e4fa80fdf8ffba4e2f2cf4df735582ed6e69599cfba413ce901abcd043f178efcf1ec6ef9072054

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 ## [Unreleased]
 
+## [2.1.0] - 2025-02-21
+
+### Added
+
+- added support for caching on type level and when calling render
+  - default cache will be set to Rails.cache in the railtie
+  - cache_key can be a string, an array, a hash or a proc
+
+## [2.0.0] - 2024-12-15
+
+### Changed
+
+- rendering undeclared http error codes (except 422) is now allowed
+  - this previously raised errors when done in endpoints with other declarations
+  - as a result, some errors rendered from `rescue_from` blocks became 500s
+- deduplicated response schemas for ad-hoc nested returns in OpenAPI export
+  - this only affects nested returns e.g. `returns :x, code: :ok, type: 'YType'`
+  - old name: `get_show_ys_200_Response`, new_name: `Y_in_x_Response`
+- removed option to render nested returns with string keys
+  - e.g. for `returns :foo, [...]`,  `render json: { 'foo' => [...] }` fails now
+- removed `Taro::Rails.declarations`, replaced it with `Taro.declarations`
+
+### Added
+
+- added `::common_return` to define common return types
+- added support for declaring path & query params as Integer
+  - e.g. `param :id, type: 'Integer', required: true` for `/users/1`
+  - e.g. `param :page, type: 'Integer', required: true` for `?page=1`
+- added parsed/rendered object to validation errors for debugging
+- improved validation error messages
+
+### Fixed
+
+- fixed unnecessary `$LOAD_PATH` searches at require time
+
 ## [1.4.0] - 2024-11-27
 
 ### Added

data/README.md

@@ -1,5 +1,8 @@
 # Taro - Typed Api using Ruby Objects
 
+[![Gem Version](https://badge.fury.io/rb/taro.svg)](https://rubygems.org/gems/taro)
+[![Build Status](https://github.com/taro-rb/taro/actions/workflows/main.yml/badge.svg)](https://github.com/taro-rb/taro/actions)
+
 This library provides an object-based type system for RESTful Ruby APIs, with built-in parameter parsing, response rendering, and OpenAPI schema export.
 
 It is inspired by [`apipie-rails`](https://github.com/Apipie/apipie-rails) and [`graphql-ruby`](https://github.com/rmosolgo/graphql-ruby).
@@ -32,25 +35,31 @@ This is how type classes can be used in a Rails controller:
 class BikesController < ApplicationController
   # This adds an endpoint summary, description, and tags to the docs (all optional)
   api     'Update a bike', desc: 'My longer text', tags: ['Bikes']
-  # Params can come from the path, e.g. /bike/:id)
+
+  # Params can come from the path, e.g. /bike/:id.
+  # Some types, like UUID in this case, are predefined. See below for more types.
   param   :id, type: 'UUID', null: false, desc: 'ID of the bike to update'
-  # They can also come from the query string or request body
+
+  # Params can also come from the query string or request body.
+  # This describes a Hash param:
   param   :bike, type: 'BikeInputType', null: false
-  # Return types can differ by status code and can be nested as in this case:
-  returns :bike, code: :ok, type: 'BikeType', desc: 'update success'
-  # This one is not nested:
-  returns code: :unprocessable_content, type: 'MyErrorType', desc: 'failure'
+
+  # Return types can differ by status code:
+  returns code: :ok, type: 'BikeType', desc: 'update success'
+
+  # Return types can also be nested (in this case in an "error" key):
+  returns :error, code: :unprocessable_content, type: 'MyErrorType'
+
   def update
-    # defined params are available as @api_params
+    # Declared params are available as @api_params
     bike = Bike.find(@api_params[:id])
     success = bike.update(@api_params[:bike])
 
-    # Types can be used to render responses.
-    # The object
+    # Types are also used to render responses.
     if success
-      render json: { bike: BikeType.render(bike) }, status: :ok
+      render json: BikeType.render(bike), status: :ok
     else
-      render json: MyErrorType.render(bike.errors.first), status: :unprocessable_entity
+      render json: { error: MyErrorType.render(bike.errors.first) }, status: :unprocessable_entity
     end
   end
 
@@ -63,18 +72,18 @@ class BikesController < ApplicationController
 end
 ```
 
-Notice the multiple roles of types: They are used to define the structure of API requests and responses, and render the response. Both the input and output of the API can be validated against the schema if desired (see below).
+Notice the multiple roles of types: They are used to describe the structure of API requests and responses, and render the response. Both the input and output of the API are validated against the schema by default (see below).
 
-Here is an example of the `BikeType` from that controller:
+Here is an example of the `BikeType` from the controller above:
 
 ```ruby
 class BikeType < ObjectType
-  # Optional description of BikeType (for API docs and the OpenAPI export)
+  # Optional description of BikeType (for the OpenAPI export)
   self.desc = 'A bike and all relevant information about it'
 
   # Object types have fields. Each field has a name, its own type,
   # and a `null:` setting to indicate if it can be nil.
-  # Providing a desc is optional.
+  # Providing a description is optional.
   field :brand, type: 'String', null: true, desc: 'The brand name'
 
   # Fields can reference other types and arrays of values
@@ -95,7 +104,9 @@ class BikeType < ObjectType
 end
 ```
 
-### Input types
+### Input and response types
+
+You can use object types for input and output. However, if you want added control, you can also define dedicated input and response types.
 
 Note the use of `BikeInputType` in the `param` declaration above? It could look like so:
 
@@ -106,7 +117,18 @@ class BikeInputType < InputType
 end
 ```
 
-The usage of such dedicated InputTypes is optional. Object types can also be used to define accepted parameters, or parts of them, depending on what you want to allow API clients to send.
+A type inheriting from InputType behaves just like an ObjectType when parsing parameters. The only difference is that it can't be used in response declarations.
+
+Likewise, there is a special type for responses, which can't be used in input declarations:
+
+```ruby
+class BikeSearchResponseType < ResponseType
+  field :bike, type: 'BikeType', null: true, desc: 'The found bike'
+  field :search_duration, type: 'Integer', null: false
+end
+```
+
+In cases where users may edit every attribute that you render, using a single ObjectType for both input and output is more convenient. E.g. `BikeType` could be used for both input and output in the `update` action above – if all its fields should be editable.
 
 ### Validation
 
@@ -120,15 +142,69 @@ Taro.config.parse_params = false
 
 #### Response validation
 
-Responses are automatically validated to use the correct type for rendering, which guarantees that they match the declaration. This can be disabled:
+Responses are automatically validated to have used the correct type for rendering, which guarantees that they match the declaration. This means you have to use the types to render complex responses, and manually building a Hash that conforms to the schema will raise an error. Primitive/scalar types are an exception, e.g. you *can* do:
+
+```ruby
+returns code: :ok, array_of: 'String', desc: 'Bike names'
+def index
+  render json: ['Super bike', 'Slow bike']
+end
+```
+
+An error is also raised if a documented endpoint renders an undocumented status code, e.g.:
+
+```ruby
+returns code: :ok, type: 'BikeType'
+def create
+  render json: BikeType.render(bike), status: :created
+  # => undeclared 201 response, raises response validation error
+end
+```
+
+HTTP error codes, except 422, are an exception. They can be rendered without prior declaration. E.g.:
+
+```ruby
+returns code: :ok, type: 'BikeType'
+def show
+  render json: something, status: :not_found # works
+end
+```
+
+The reason for this is that Rack and Rails commonly render codes like 400, 404, 500 and various others, but you might not want to have that fact documented on every single endpoint.
+
+However, if you do declare an error code, responses with this code *are* validated:
+
+```ruby
+returns code: :not_found, type: 'ExpectedErrorType'
+def show
+  render json: WrongErrorType.render(foo), status: :not_found
+  # => type mismatch, raises response validation error
+end
+```
+
+Response validation can be disabled:
 
 ```ruby
 Taro.config.validate_responses = false
 ```
 
+### Common error declarations
+
+`::common_return` can be used to add a return declaration to all actions in a controller and its subclasses, and all related OpenAPI exports.
+
+```ruby
+class AuthenticatedApiBaseController < ApiBaseController
+  common_return code: :unauthorized, type: 'MyErrorType', desc: 'Log in first'
+
+  rescue_from 'MyAuthError' do
+    render json: MyErrorType.render(something), status: :unauthorized
+  end
+end
+```
+
 ### Included type options
 
-The following type names are available by default and can be used as `type:`/`array_of:`/`page_of:` arguments:
+The following type names are available by default and can be used as `type:`, `array_of:`, or `page_of:` arguments:
 
 - `'Boolean'` - accepts and renders `true` or `false`
 - `'Date'` - accepts and renders a date string in ISO8601 format
@@ -142,7 +218,7 @@ The following type names are available by default and can be used as `type:`/`ar
 - `'Timestamp'` - renders a `Time` as unix timestamp integer and turns incoming integers into a `Time`
 - `'UUID'` - accepts and renders UUIDs
 
-Also, when using the generator, `ErrorsType` and `ErrorDetailsType` are generated as a starting point for unified error presentation. `ErrorsType` can render invalid `ActiveRecord` instances, `ActiveModel::Errors` and other data structures.
+Also, when using the rails generator, `ErrorsType` and `ErrorDetailsType` are generated as a starting point for unified error presentation. `ErrorsType` can render invalid `ActiveRecord` instances, `ActiveModel::Errors` and other data structures.
 
 ### Enums
 
@@ -168,38 +244,13 @@ class ErrorType < ObjectType
 end
 ```
 
-### FAQ
-
-#### How do I avoid repeating common error declarations?
-
-Hook into the DSL in your base controller(s):
-
-```ruby
-class ApiBaseController < ApplicationController
-  def self.api(...)
-    super
-    returns code: :not_found, type: 'MyErrorType', desc: 'The record was not found'
-  end
+## FAQ
 
-  rescue_from ActiveRecord::RecordNotFound, with: :render_not_found
+### How do I render API docs?
 
-  def render_not_found
-    render json: MyErrorType.render(something), status: :not_found
-  end
-end
-```
+Rendering docs is outside of the scope of this project. You can use the OpenAPI export to generate docs with tools such as RapiDoc, ReDoc, Swagger UI, and [many others](https://tools.openapis.org/categories/documentation.html).
 
-```ruby
-class AuthenticatedApiController < ApiBaseController
-  def self.api(...)
-    super
-    returns code: :unauthorized, type: 'MyErrorType'
-  end
-  # ... rescue_from ... render ...
-end
-```
-
-#### How do I use context in my types?
+### How do I use context in my types?
 
 Use [ActiveSupport::CurrentAttributes](https://api.rubyonrails.org/classes/ActiveSupport/CurrentAttributes.html).
 
@@ -213,18 +264,23 @@ class BikeType < ObjectType
 end
 ```
 
-#### How do I migrate from apipie-rails?
+### How do I migrate from apipie-rails?
+
+First of all, if you don't need a better OpenAPI export, or better support for hashes and arrays, or less repetitive definitions, it might not be worth it.
+
+Please also note the following:
 
-First of all, if you don't need a better OpenAPI export, or better support for hashes and arrays, it might not be worth it.
+- `taro` currently only supports the latest OpenAPI standard (instead of v2 like `apipie-rails`)
+- `taro` does not support arbitrary validations - only those that can be expressed in the OpenAPI schema
+- `taro` does not render API docs, as mentioned above
 
-If you do:
+If you want to migrate anyway:
 
-- note that `taro` currently only supports the latest OpenAPI standard (instead of v2 like `apipie-rails`)
 - extract complex param declarations into InputTypes
-- extract complex response declarations into ObjectTypes
+- extract complex response declarations into ObjectTypes or ResponseTypes
 - replace `required: true` with `null: false` and `required: false` with `null: true`
 
-For a step-by-step migration, you might want to make `taro` use a different DSL then `apipie`:
+Taro uses some of the same DSL as `apipie`, so for a step-by-step migration, you might want to make `taro` use a different one. This initializer will change the `taro` DSL to `taro_api`, `taro_param`, and `taro_returns` and leave `api`, `param`, and `returns` to `apipie`:
 
 ```ruby
 # config/initializers/taro.rb
@@ -234,7 +290,7 @@ For a step-by-step migration, you might want to make `taro` use a different DSL
 end
 ```
 
-#### How do I keep lengthy API descriptions out of my controller?
+### How do I keep lengthy API descriptions out of my controller?
 
 ```ruby
 module BikeUpdateDesc
@@ -252,13 +308,13 @@ class BikesController < ApplicationController
 end
 ```
 
-#### Why do I have to use type name strings instead of the type constants?
+### Why do I have to use type name strings instead of the type constants?
 
 Why e.g. `field :id, type: 'UUID'` instead of `field :id, type: UUID`?
 
 The purpose of this is to reduce unnecessary autoloading of the whole type dependency tree in dev and test environments.
 
-#### Can I define my own derived types like `page_of` or `array_of`?
+### Can I define my own derived types like `page_of` or `array_of`?
 
 Yes.
 
@@ -288,15 +344,37 @@ class MyController < ApplicationController
 end
 ```
 
+## Caching
+
+Taro provides support for caching. The cache instance can be configured by setting `Taro::Cache.cache_instance`. By default, the railtie will set it to `Rails.cache`.
+
+It supports configuring an add hoc cache when using a render call, e.g.
+
+```ruby
+bike = Bike.find(params[:id])
+BikeType.with_cache(cache_key: bike.cache_key, expires_in: 3.minutes).render(bike)
+```
+
+Or by configuring the cache rule on a per type bases, e.g.
+
+```ruby
+class BikeType < ObjectType
+  # Optional description of BikeType (for the OpenAPI export)
+  self.desc = 'A bike and all relevant information about it'
+  self.cache_key = ->(bike) { bike.cache_key_with_version }
+  self.expires_in = 1.hour
+
+  ...
+end
+```
+
 ## Possible future features
 
 - warning/raising for undeclared input params (currently they are ignored)
 - usage without rails is possible but not convenient yet
 - rspec matchers for testing
 - sum types
-- api doc rendering based on export (e.g. rails engine with web ui)
 - [query logs metadata](https://github.com/rmosolgo/graphql-ruby/blob/dcaaed1cea47394fad61fceadf291ff3cb5f2932/lib/generators/graphql/install_generator.rb#L48-L52)
-- maybe make `type:` optional for path params as they're always strings anyway
 - various openapi features
   - non-JSON content types (e.g. for file uploads)
   - [examples](https://swagger.io/specification/#example-object)

data/lib/taro/cache.rb

@@ -0,0 +1,14 @@
+module Taro::Cache
+  singleton_class.attr_accessor :cache_instance
+
+  def self.call(object, cache_key: nil, expires_in: nil)
+    case cache_key
+    when nil
+      yield
+    when Hash, Proc
+      call(object, cache_key: cache_key[object], expires_in: expires_in) { yield }
+    else
+      cache_instance.fetch(cache_key, expires_in: expires_in) { yield }
+    end
+  end
+end

data/lib/taro/common_returns.rb

@@ -0,0 +1,31 @@
+# Holds common return definitions for a set of declarations,
+# e.g. shared error responses, within a class and its subclasses.
+module Taro::CommonReturns
+  class << self
+    def define(klass, nesting = nil, **)
+      (map[klass] ||= []) << Taro::ReturnDef.new(nesting:, **)
+      klass.extend(InheritedCallback)
+    end
+
+    def inherit(from_class, to_class)
+      map[to_class] = map[from_class].dup
+    end
+
+    def for(klass)
+      map[klass] || []
+    end
+
+    private
+
+    def map
+      @map ||= {}
+    end
+  end
+
+  module InheritedCallback
+    def inherited(new_class)
+      Taro::CommonReturns.inherit(self, new_class)
+      super
+    end
+  end
+end

data/lib/taro/declaration.rb

@@ -0,0 +1,82 @@
+# Framework-agnostic, abstract class.
+# Descendants must implement #endpoint and (only for openapi export) #routes.
+# See Taro::Rails::Declaration for an example.
+class Taro::Declaration
+  attr_reader :desc, :summary, :params, :return_defs, :return_descriptions, :tags
+
+  def initialize(for_klass = nil)
+    @params = Class.new(Taro::Types::InputType)
+    @return_defs = {}
+    @return_descriptions = {}
+
+    Taro::CommonReturns.for(for_klass).each { |rd| add_return_def(rd) }
+  end
+
+  def add_info(summary, desc: nil, tags: nil)
+    summary.is_a?(String) || raise(Taro::ArgumentError, 'api summary must be a String')
+    @summary = summary
+    @desc = desc
+    @tags = Array(tags) if tags
+  end
+
+  def add_param(param_name, **attributes)
+    if attributes[:type] == 'Integer'
+      attributes[:type] = 'Taro::Types::Scalar::IntegerParamType'
+    end
+    @params.field(param_name, **attributes)
+  end
+
+  def add_return(nesting = nil, **)
+    return_def = Taro::ReturnDef.new(nesting:, **)
+    add_return_def(return_def)
+  end
+
+  # Return types are evaluated lazily to avoid unnecessary autoloading
+  # of all types in dev/test envs.
+  def returns
+    @returns ||= evaluate_return_defs
+  end
+
+  def routes
+    raise NotImplementedError, "implement ##{__method__} in subclass"
+  end
+
+  def endpoint
+    raise NotImplementedError, "implement ##{__method__} in subclass"
+  end
+
+  def polymorphic_route?
+    routes.size > 1
+  end
+
+  def inspect
+    "#<#{self.class} (#{endpoint || 'not finalized'})>"
+  end
+
+  private
+
+  def add_return_def(return_def)
+    raise_if_already_declared(return_def.code)
+
+    return_defs[return_def.code] = return_def
+    return_descriptions[return_def.code] = return_def.desc
+  end
+
+  def raise_if_already_declared(code)
+    (prev = return_defs[code]) && raise(Taro::ArgumentError, <<~MSG)
+      response for status #{code} already declared at #{prev.defined_at}
+    MSG
+  end
+
+  def evaluate_return_defs
+    return_defs.transform_values do |rd|
+      type = rd.evaluate
+      type.define_name("ResponseType(#{endpoint})") if rd.nesting
+      type
+    end
+  end
+
+  def <=>(other)
+    routes.first.openapi_operation_id <=> other.routes.first.openapi_operation_id
+  end
+end

data/lib/taro/declarations.rb

@@ -0,0 +1,34 @@
+module Taro
+  def self.declarations
+    DeclarationsMap
+  end
+
+  module DeclarationsMap
+    class << self
+      include Enumerable
+
+      def [](key)
+        map[key]
+      end
+
+      def []=(key, declaration)
+        map.key?(key) && raise(Taro::InvariantError, "#{key} already declared")
+        map[key] = declaration
+      end
+
+      def each(&)
+        map.each_value(&)
+      end
+
+      def reset
+        map.clear
+      end
+
+      private
+
+      def map
+        @map ||= {}
+      end
+    end
+  end
+end

data/lib/taro/errors.rb

@@ -1,12 +1,25 @@
 class Taro::Error < StandardError
   def message
     # clean up newlines introduced when setting the message with a heredoc
-    super.chomp.sub(/\n(?=\S)/, ' ')
+    super.chomp.tr("\n", ' ')
   end
 end
 
 class Taro::ArgumentError < Taro::Error; end
 class Taro::RuntimeError < Taro::Error; end
-class Taro::ValidationError < Taro::RuntimeError; end # not to be used directly
+class Taro::InvariantError < Taro::RuntimeError; end
+
+class Taro::ValidationError < Taro::RuntimeError
+  attr_reader :object, :origin
+
+  def initialize(message, object, origin)
+    raise 'Abstract class' if instance_of?(Taro::ValidationError)
+
+    super(message)
+    @object = object
+    @origin = origin
+  end
+end
+
 class Taro::InputError < Taro::ValidationError; end
 class Taro::ResponseError < Taro::ValidationError; end

data/lib/taro/export/base.rb

@@ -1,7 +1,7 @@
 class Taro::Export::Base
   attr_reader :result
 
-  def self.call(declarations:, title: 'Taro-based API', version: '1.0', **)
+  def self.call(declarations: Taro.declarations, title: Taro.config.api_name, version: Taro.config.api_version, **)
     new.call(declarations:, title:, version:, **)
   end
 

data/lib/taro/export/open_api_v3.rb

@@ -6,8 +6,6 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
     @schemas = {}
   end
 
-  # TODO:
-  # - use json-schema gem to validate overall result against OpenAPIv3 schema
   def call(declarations:, title:, version:)
     @result = { openapi: '3.1.0', info: { title:, version: } }
     paths = export_paths(declarations)
@@ -34,7 +32,7 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
         operationId: route.openapi_operation_id,
         parameters: route_parameters(declaration, route),
         requestBody: request_body(declaration, route),
-        responses: responses(declaration, route),
+        responses: responses(declaration),
       }.compact,
     }
   end
@@ -45,9 +43,10 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
 
   def path_parameters(declaration, route)
     route.path_params.map do |param_name|
-      param_field = declaration.params.fields[param_name] || raise(<<~MSG)
-        Declaration missing for path param #{param_name} of route #{route.endpoint}
-      MSG
+      param_field = declaration.params.fields[param_name] || raise(
+        Taro::InvariantError,
+        "Declaration missing for path param #{param_name} of route #{route}"
+      )
 
       # path params are always required in rails
       export_parameter(param_field).merge(in: 'path', required: true)
@@ -77,8 +76,11 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
   end
 
   def validate_path_or_query_parameter(field)
-    [:array, :object].include?(field.type.openapi_type) &&
-      raise("Unexpected object as path/query param #{field.name}: #{field.type}")
+    ok = %i[string integer]
+    ok.include?(field.type.openapi_type) || raise(Taro::ArgumentError, <<~MSG)
+      Unsupported #{field.openapi_type} as path/query param "#{field.name}",
+      expected one of: #{ok.join(', ')}
+    MSG
   end
 
   def request_body(declaration, route)
@@ -110,28 +112,21 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
     end
   end
 
-  def responses(declaration, route)
-    name_anonymous_return_types(declaration, route)
-
+  def responses(declaration)
     declaration.returns.sort.to_h do |code, type|
+      # response description is required in openapi 3 – fall back to status code
+      description = declaration.return_descriptions[code] || type.desc ||
+                    Taro::StatusCode.coerce_to_message(code)
       [
         code.to_s,
         {
-          description: declaration.return_descriptions[code],
+          description:,
           content: { 'application/json': { schema: export_type(type) } },
         }
       ]
     end
   end
 
-  def name_anonymous_return_types(declaration, route)
-    declaration.returns.each do |code, type|
-      next if type.openapi_name?
-
-      type.openapi_name = "#{route.openapi_operation_id}_#{code}_Response"
-    end
-  end
-
   def export_type(type)
     if type < Taro::Types::ScalarType && !custom_scalar_type?(type)
       { type: type.openapi_type }
@@ -199,7 +194,7 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
     elsif custom_scalar_type?(type)
       custom_scalar_type_details(type)
     else
-      raise NotImplementedError, "Unsupported type: #{type}"
+      raise Taro::InvariantError, "Unexpected type: #{type}"
     end
   end
 
@@ -244,8 +239,10 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
 
   def assert_unique_openapi_name(type)
     @name_to_type_map ||= {}
-    if (prev = @name_to_type_map[type.openapi_name]) && type != prev
-      raise("Duplicate openapi_name \"#{type.openapi_name}\" for types #{prev} and #{type}")
+    if (prev = @name_to_type_map[type.openapi_name]) && !prev.equivalent?(type)
+      raise Taro::InvariantError, <<~MSG
+        Duplicate openapi_name "#{type.openapi_name}" for types #{prev} and #{type}
+      MSG
     else
       @name_to_type_map[type.openapi_name] = type
     end