taro 1.4.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d30f413c950e02e52f99ed96d234acdba122c92ec4e39dd2d35e87c899ed8a13
-  data.tar.gz: 5ed455623397ce6fbcb19412710bf98bc7ca2b6898db193a2cf858104a149327
+  metadata.gz: 62127cdef8f44e34831cb4dec7d900bfa25c3c00994e750624de1f486c6880ab
+  data.tar.gz: 40bd31112d3e8fb3fe96bfa282acd6ad909c60f66431aa556e01052b3098ab44
 SHA512:
-  metadata.gz: ba99529dd914238371708a80b5f3f6497a4884a042a0e11ec7e9b557107379d0bfa2232b6a71137623658651e5d920f8ad47ab683119ae5ce105261fa627b980
-  data.tar.gz: 26b2652184c485aa7970707373cfe4ebfdecd3141fc7e995066060b5a0a5452b1e749d6e16fdc3d99e34a199434ed9edc7400d89fe8f8ed32df442d764d06175
+  metadata.gz: a609041860bc3516a70a1ebd2f073d031cac39a04f9ff5562ff7c6d0711b1c5dc3a900cfa4842ff77f6ab573ab0fa2164282cf68fff58133071a7b842201cecc
+  data.tar.gz: 4942e27cdc067cb5c46ae7f726743d1cf54282536195b892d93507757820e0c53db46ebfb5a40ad25cc13c60ef2eac6b493cb1e2d8b9cfa195a0db782734d765

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 ## [Unreleased]
 
+## [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

@@ -32,25 +32,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.
   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 +69,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 +101,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 +114,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,12 +139,59 @@ 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.
+
+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
+```
+
+However, all HTTP error codes except 422 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: 'ExpectedType'
+def show
+  render json: WrongType.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:
@@ -170,34 +236,9 @@ end
 
 ### FAQ
 
-#### How do I avoid repeating common error declarations?
-
-Hook into the DSL in your base controller(s):
+#### How do I render API docs?
 
-```ruby
-class ApiBaseController < ApplicationController
-  def self.api(...)
-    super
-    returns code: :not_found, type: 'MyErrorType', desc: 'The record was not found'
-  end
-
-  rescue_from ActiveRecord::RecordNotFound, with: :render_not_found
-
-  def render_not_found
-    render json: MyErrorType.render(something), status: :not_found
-  end
-end
-```
-
-```ruby
-class AuthenticatedApiController < ApiBaseController
-  def self.api(...)
-    super
-    returns code: :unauthorized, type: 'MyErrorType'
-  end
-  # ... rescue_from ... render ...
-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, or Swagger UI.
 
 #### How do I use context in my types?
 
@@ -215,16 +256,16 @@ end
 
 #### 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, it might not be worth it.
+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.
 
 If you do:
 
 - 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:
 
 ```ruby
 # config/initializers/taro.rb
@@ -294,9 +335,7 @@ end
 - 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/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

data/lib/taro/export.rb

@@ -1,3 +1,3 @@
 module Taro::Export
-  Dir[File.join(__dir__, "export", "*.rb")].each { |f| require f }
+  Dir[File.join(__dir__, "export", "*.rb")].each { |f| require_relative f }
 end

data/lib/taro/none.rb

@@ -0,0 +1,2 @@
+# placeholder for not-given keyword arguments
+Taro::None = Object.new

data/lib/taro/rails/active_declarations.rb

@@ -1,19 +1,11 @@
 module Taro::Rails::ActiveDeclarations
   def apply(declaration:, controller_class:, action_name:)
-    (declarations_map[controller_class] ||= {})[action_name] = declaration
+    Taro.declarations["#{controller_class.name}##{action_name}"] = declaration
     Taro::Rails::ParamParsing.install(controller_class:, action_name:)
     Taro::Rails::ResponseValidation.install(controller_class:)
   end
 
-  def declarations_map
-    @declarations_map ||= {}
-  end
-
-  def declarations
-    declarations_map.values.flat_map(&:values)
-  end
-
   def declaration_for(controller)
-    declarations_map[controller.class].to_h[controller.action_name.to_sym]
+    Taro.declarations["#{controller.class.name}##{controller.action_name}"]
   end
 end