taro 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d810edb4a339ca65e24bed6cbecf1baf1f83f84f7894589e8db69a09bc9b3f23
-  data.tar.gz: eaef44afdc12b965d93fd4532efadf41025c30fd59eb87281ae5815c6f48bcf7
+  metadata.gz: 5007f07dcb3230a1a45011138c19cc0f233e0a0e0fa81d64d554ee3d5cc4a82e
+  data.tar.gz: 99dde57ec71bb2724a29005e644a0bb23d642df11fe4555bd9203340169814df
 SHA512:
-  metadata.gz: f2de8020efb8ede1493d10cb798d69fa92201d2b518177a527d0e2546e771afe8fa436f03dd839c4a75d655cc2eab26fdb35c4d37a830393fda4e37bfd6583c5
-  data.tar.gz: ca421c1f360b072570f7eab0b17c26ac2109f16a19d96efbe564d22e791f7fa0945d11eb914ff67b29602576499f03aed388fc10cad6f9b7b1f42bea4f905f7d
+  metadata.gz: abb5fb481da01a4a50b19e891c3373b42372c97993788ed24c51b07146e087e25d040bc4ea077606a14013633b30f6254f6ced2e939ba9b039b341d95f918211
+  data.tar.gz: b5dd6c2222598ad3d8ee64c64fd0fc6c40299c3f071b08317d17aa29c3f786924ae4b064f587b1e548ba102e0cc802b8a5adf7ccbadf033795974bfdaae5329a

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 ## [Unreleased]
 
-## [0.1.0] - 2024-11-03
+## [1.2.0] - 2024-11-18
+
+### Added
+
+- Improved error messages
+- Option to define custom derived types
+- Option to use custom keys in paginated content
+- Option to deprecate individual fields, params, and types
+
+### Fixed
+
+- Fixed nullable enum fields raising for null input
+- Fixed auto-loading of return types
+- Fixed console spam when inspecting declarations
+- Fixed resolver method not being used when rendering a Hash
+- Fixed the ErrorsType template
+- Many fixes for OpenAPI export
+  - Fixed export of parameters for http methods without body
+  - Fixed export for PageType
+  - Fixed export for arrays of UUIDs, Dates, and Times
+  - Fixed export YML keys for namespaced controllers
+  - Reference plain types for repeated flat return types
+  - Made order of paths, verbs, responses and schemas deterministic
+
+## [1.1.0] - 2024-11-16
+
+### Added
+
+- Response validation refined
+
+### Fixed
+
+- Bugfix for openapi export
+
+## [1.0.0] - 2024-11-14
 
 - Initial release

data/README.md

@@ -10,11 +10,6 @@ It is inspired by [`apipie-rails`](https://github.com/Apipie/apipie-rails) and [
 - conveniently check request and response data against the declaration
 - offer an up-to-date OpenAPI export with minimal configuration
 
-## ⚠️ This is a work in progress - TODO:
-
-- ISO8601Time, ISO8601Date types
-- ResponseValidation: allow rendering scalars directly (e.g. `render json: 42`)
-
 ## Installation
 
 ```bash
@@ -136,16 +131,18 @@ Taro.config.validate_responses = false
 The following type names are available by default and can be used as `type:`/`array_of:`/`page_of:` arguments:
 
 - `'Boolean'` - accepts and renders `true` or `false`
+- `'Date'` - accepts and renders a date string in ISO8601 format
+- `'DateTime'` - an alias for `'Time'`
 - `'Float'`
 - `'FreeForm'` - accepts and renders any JSON-serializable object, use with care
 - `'Integer'`
-- `'NoContentType'` - renders an empty object, for use with `status: :no_content`
+- `'NoContent'` - renders an empty object, for use with `status: :no_content`
 - `'String'`
-- `'Timestamp'` - renders a `Time` as unix timestamp integer and turns into incoming integers into a `Time`
-- `'UUID'` - accepts and renders UUIDs
-- `'Date'` - accepts and renders a date string in ISO8601 format
 - `'Time'` - accepts and renders a time string in ISO8601 format
-- `'DateTime'` - an alias for `'Time'`
+- `'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.
 
 ### Enums
 
@@ -173,7 +170,7 @@ end
 
 ### FAQ
 
-#### How to avoid repeating common error declarations?
+#### How do I avoid repeating common error declarations?
 
 Hook into the DSL in your base controller(s):
 
@@ -202,7 +199,7 @@ class AuthenticatedApiController < ApiBaseController
 end
 ```
 
-#### How to use context in my types?
+#### How do I use context in my types?
 
 Use [ActiveSupport::CurrentAttributes](https://api.rubyonrails.org/classes/ActiveSupport/CurrentAttributes.html).
 
@@ -216,13 +213,80 @@ class BikeType < ObjectType
 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.
+
+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
+- 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`:
+
+```ruby
+# config/initializers/taro.rb
+%i[api param returns].each do |m|
+  Taro::Rails::DSL.alias_method("taro_#{m}", m) # `taro_api` etc.
+  Taro::Rails::DSL.define_method(m) { |*a, **k, &b| super(*a, **k, &b) }
+end
+```
+
+#### How do I keep lengthy API descriptions out of my controller?
+
+```ruby
+module BikeUpdateDesc
+  extend ActiveSupport::Concern
+
+  included do
+    api 'Update a bike', description: 'Long description', tags: ['Bikes']
+    # lots of params and returns ...
+  end
+end
+
+class BikesController < ApplicationController
+  include BikeUpdateDesc
+  def update # ...
+end
+```
+
 #### 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.
 
-This already works fo type classes – they don't trigger loading of referenced types unless used. The API declarations in controller classes still trigger auto-loading for now, but we aim to improve this in the future.
+#### Can I define my own derived types like `page_of` or `array_of`?
+
+Yes.
+
+```ruby
+# Implement ::derive_from in your custom type.
+class PreviewType < Taro::Types::Scalar::StringType
+  singleton_class.attr_reader :type_to_preview
+
+  def self.derive_from(other_type)
+    self.type_to_preview = other_type
+  end
+
+  def coerce_response
+    type_to_preview.new(object).coerce_response.to_s.truncate(100)
+  end
+end
+
+# Make it available in the DSL, e.g. in an initializer.
+Taro::Types::BaseType.define_derived_type :preview, 'PreviewType'
+
+# Usage:
+class MyController < ApplicationController
+  returns code: :ok, preview_of: 'BikeType'
+  def show
+    render json: BikeType.preview.render(Bike.find(params[:id]))
+  end
+end
+```
 
 ## Possible future features
 
@@ -232,7 +296,6 @@ This already works fo type classes – they don't trigger loading of referenced
 - 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)
-- deprecation feature
 - 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)

data/lib/taro/errors.rb

@@ -1,4 +1,10 @@
-class Taro::Error < StandardError; end
+class Taro::Error < StandardError
+  def message
+    # clean up newlines introduced when setting the message with a heredoc
+    super.chomp.sub(/\n(?=\S)/, ' ')
+  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

data/lib/taro/export/open_api_v3.rb

@@ -11,15 +11,16 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
   def call(declarations:, title:, version:)
     @result = { openapi: '3.1.0', info: { title:, version: } }
     paths = export_paths(declarations)
-    @result[:paths] = paths if paths.any?
-    @result[:components] = { schemas: } if schemas.any?
+    @result[:paths] = paths.sort.to_h if paths.any?
+    @result[:components] = { schemas: schemas.sort.to_h } if schemas.any?
     self
   end
 
   def export_paths(declarations)
-    declarations.each_with_object({}) do |declaration, paths|
+    declarations.sort.each_with_object({}) do |declaration, paths|
       declaration.routes.each do |route|
-        paths[route.openapi_path] = export_route(route, declaration)
+        paths[route.openapi_path] ||= {}
+        paths[route.openapi_path].merge! export_route(route, declaration)
       end
     end
   end
@@ -30,30 +31,51 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
         description: declaration.desc,
         summary: declaration.summary,
         tags: declaration.tags,
-        parameters: path_parameters(declaration, route),
+        parameters: route_parameters(declaration, route),
         requestBody: request_body(declaration, route),
         responses: responses(declaration),
       }.compact,
     }
   end
 
+  def route_parameters(declaration, route)
+    path_parameters(declaration, route) + query_parameters(declaration, route)
+  end
+
   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
 
-      {
-        name: param_field.name,
-        in: 'path',
-        description: param_field.desc,
-        required: true, # path params are always required in rails
-        schema: { type: param_field.openapi_type },
-      }.compact
+      # path params are always required in rails
+      export_parameter(param_field).merge(in: 'path', required: true)
     end
   end
 
+  def query_parameters(declaration, route)
+    return [] if route.can_have_request_body?
+
+    declaration.params.fields.filter_map do |name, param_field|
+      next if route.path_params.include?(name)
+
+      export_parameter(param_field).merge(in: 'query')
+    end
+  end
+
+  def export_parameter(field)
+    {
+      name: field.name,
+      deprecated: field.deprecated,
+      description: field.desc,
+      required: !field.null,
+      schema: { type: field.openapi_type },
+    }.compact
+  end
+
   def request_body(declaration, route)
+    return unless route.can_have_request_body?
+
     params = declaration.params
     body_param_fields = params.fields.reject do |name, _field|
       route.path_params.include?(name)
@@ -81,7 +103,7 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
   end
 
   def responses(declaration)
-    declaration.returns.to_h do |code, type|
+    declaration.returns.sort.to_h do |code, type|
       [
         code.to_s,
         {
@@ -114,23 +136,29 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
     # as it puts props like format together with the main type.
     # https://github.com/OAI/OpenAPI-Specification/issues/3148
     base = { oneOf: [base, { type: 'null' }] } if field.null
-    base[:description] = field.desc if field.desc
-    base[:default] = field.default if field.default_specified?
-    base[:enum] = field.enum if field.enum
-    base
+    base.merge(field_metadata(field))
   end
 
   def export_complex_field_ref(field)
     ref = extract_component_ref(field.type)
+    return ref if field_metadata(field).empty? && !field.null
+
     if field.null
       # RE nullable: https://stackoverflow.com/a/70658334
-      { description: field.desc, oneOf: [ref, { type: 'null' }] }.compact
-    elsif field.desc
+      { oneOf: [ref, { type: 'null' }] }
+    else # i.e. with metadata such as description or deprecated
       # https://github.com/OAI/OpenAPI-Specification/issues/2033
-      { description: field.desc, allOf: [ref] }
-    else
-      ref
-    end
+      { allOf: [ref] }
+    end.merge(field_metadata(field))
+  end
+
+  def field_metadata(field)
+    meta = {}
+    meta[:description] = field.desc if field.desc
+    meta[:deprecated] = field.deprecated unless field.deprecated.nil?
+    meta[:default] = field.default if field.default_specified?
+    meta[:enum] = field.enum if field.enum
+    meta
   end
 
   def extract_component_ref(type)
@@ -155,6 +183,7 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
     required = type.fields.values.reject(&:null).map(&:name)
     {
       type: type.openapi_type,
+      deprecated: type.deprecated,
       description: type.desc,
       required: (required if required.any?),
       properties: type.fields.to_h { |name, f| [name, export_field(f)] },
@@ -165,6 +194,7 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
   def enum_type_details(enum)
     {
       type: enum.item_type.openapi_type,
+      deprecated: enum.deprecated,
       description: enum.desc,
       enum: enum.values,
     }.compact
@@ -173,6 +203,7 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
   def list_type_details(list)
     {
       type: 'array',
+      deprecated: list.deprecated,
       description: list.desc,
       items: export_type(list.item_type),
     }.compact

data/lib/taro/rails/active_declarations.rb

@@ -2,7 +2,7 @@ module Taro::Rails::ActiveDeclarations
   def apply(declaration:, controller_class:, action_name:)
     (declarations_map[controller_class] ||= {})[action_name] = declaration
     Taro::Rails::ParamParsing.install(controller_class:, action_name:)
-    Taro::Rails::ResponseValidation.install(controller_class:, action_name:)
+    Taro::Rails::ResponseValidation.install(controller_class:)
   end
 
   def declarations_map

data/lib/taro/rails/declaration.rb

@@ -1,9 +1,9 @@
 class Taro::Rails::Declaration
-  attr_reader :desc, :summary, :params, :returns, :return_descriptions, :return_nestings, :routes, :tags
+  attr_reader :desc, :summary, :params, :return_defs, :return_descriptions, :return_nestings, :routes, :tags
 
   def initialize
     @params = Class.new(Taro::Types::InputType)
-    @returns = {}
+    @return_defs = {}
     @return_descriptions = {}
     @return_nestings = {}
   end
@@ -24,8 +24,11 @@ class Taro::Rails::Declaration
     status = self.class.coerce_status_to_int(code)
     raise_if_already_declared(status)
 
+    kwargs[:nesting] = nesting
+    check_return_kwargs(kwargs)
+
     kwargs[:defined_at] = caller_locations(1..2)[1]
-    returns[status] = return_type_from(nesting, **kwargs)
+    return_defs[status] = kwargs
 
     # response desc is required in openapi 3 – fall back to status code
     return_descriptions[status] = desc || code.to_s
@@ -34,14 +37,19 @@ class Taro::Rails::Declaration
     return_nestings[status] = nesting if nesting
   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 raise_if_already_declared(status)
-    returns[status] &&
+    return_defs[status] &&
       raise(Taro::ArgumentError, "response for status #{status} already declared")
   end
 
   def parse_params(rails_params)
-    hash = params.new(rails_params.to_unsafe_h).coerce_input
-    hash
+    params.new(rails_params.to_unsafe_h).coerce_input
   end
 
   def finalize(controller_class:, action_name:)
@@ -67,10 +75,15 @@ class Taro::Rails::Declaration
   # TODO: these change when the controller class is renamed.
   # We might need a way to set `base`. Perhaps as a kwarg to `::api`?
   def add_openapi_names(controller_class:, action_name:)
-    base = "#{controller_class.name.chomp('Controller').sub('::', '_')}_#{action_name}"
+    base = "#{controller_class.name.chomp('Controller').gsub('::', '_')}_#{action_name}"
     params.openapi_name = "#{base}_Input"
+    params.define_singleton_method(:name) { openapi_name }
+
     returns.each do |status, return_type|
+      next if return_type.openapi_name? # only set for ad-hoc / nested return types
+
       return_type.openapi_name = "#{base}_#{status}_Response"
+      return_type.define_singleton_method(:name) { openapi_name }
     end
   end
 
@@ -86,10 +99,34 @@ class Taro::Rails::Declaration
 
   private
 
-  def return_type_from(nesting, **kwargs)
+  def check_return_kwargs(kwargs)
+    # For nested returns, evaluate_return_def calls ::field, which validates
+    # field options, but does not trigger type autoloading.
+    return evaluate_return_def(**kwargs) if kwargs[:nesting]
+
+    if kwargs.key?(:null)
+      raise Taro::ArgumentError, <<~MSG
+        `null:` is not supported for top-level returns. If you want a nullable return
+        value, nest it, e.g. `returns :str, type: 'String', null: true`.
+      MSG
+    end
+
+    bad_keys = kwargs.keys - (Taro::Types::Coercion.keys + %i[code desc nesting])
+    return if bad_keys.empty?
+
+    raise Taro::ArgumentError, "Invalid `returns` options: #{bad_keys.join(', ')}"
+  end
+
+  def evaluate_return_defs
+    return_defs.transform_values { |defi| evaluate_return_def(**defi) }
+  end
+
+  def evaluate_return_def(nesting:, **kwargs)
     if nesting
       # ad-hoc return type, requiring the actual return type to be nested
-      Class.new(Taro::Types::ObjectType).tap { |t| t.field(nesting, **kwargs) }
+      Class.new(Taro::Types::ObjectType).tap do |type|
+        type.field(nesting, null: false, **kwargs)
+      end
     else
       Taro::Types::Coercion.call(kwargs)
     end
@@ -98,4 +135,8 @@ class Taro::Rails::Declaration
   def raise_missing_route(controller_class, action_name)
     raise(Taro::ArgumentError, "No route found for #{controller_class}##{action_name}")
   end
+
+  def <=>(other)
+    params.openapi_name <=> other.params.openapi_name
+  end
 end

data/lib/taro/rails/generators/install_generator.rb

@@ -12,7 +12,7 @@ class Taro::Rails::Generators::InstallGenerator < ::Rails::Generators::Base
   def create_type_files
     Dir["#{self.class.source_root}/**/*.erb"].each do |tmpl|
       dest_dir = options[:dir].chomp('/')
-      copy_file tmpl, "#{dest_dir}/#{File.basename(tmpl).sub('erb', 'rb')}"
+      template tmpl, "#{dest_dir}/#{File.basename(tmpl).sub('erb', 'rb')}"
     end
   end
   # :nocov:

data/lib/taro/rails/generators/templates/errors_type.erb

@@ -11,15 +11,20 @@ class ErrorsType < Taro::Types::ListType
   end
 
   def coerce_response
-    case object.class.name
-    when 'ActiveRecord::Base'
-      super(object.errors.errors)
-    when 'ActiveModel::Errors'
-      super(object.errors)
-    when 'Hash', 'Interactor::Context'
-      super(object[:errors])
-    else # e.g. Array
-      super(object)
-    end
+    list =
+      case object<%- if defined?(ActiveRecord) %>
+      when ActiveModel::Errors
+        object.errors
+      when ActiveRecord::Base
+        object.errors.errors<%- end %>
+      when Array
+        object
+      when Hash<%- if defined?(Interactor::Context) %>, Interactor::Context<%- end %>
+        object.to_h.fetch(:errors)
+      else
+        response_error("must be an Enumerable or an object with errors")
+      end
+
+    list.map { |el| self.class.item_type.new(el).coerce_response }
   end
 end

data/lib/taro/rails/normalized_route.rb

@@ -26,4 +26,12 @@ Taro::Rails::NormalizedRoute = Data.define(:rails_route) do
     controller, action = rails_route.requirements.values_at(:controller, :action)
     "#{controller}##{action}"
   end
+
+  def can_have_request_body?
+    %w[patch post put].include?(verb)
+  end
+
+  def inspect
+    %(#<#{self.class} "#{verb} #{openapi_path}">)
+  end
 end

data/lib/taro/rails/response_validation.rb

@@ -1,63 +1,13 @@
 module Taro::Rails::ResponseValidation
-  def self.install(controller_class:, action_name:)
-    return unless Taro.config.validate_response
-
-    key = [controller_class, action_name]
-    return if installed[key]
-
-    installed[key] = true
-
-    controller_class.around_action(only: action_name) do |_, block|
-      Taro::Types::BaseType.rendering = nil
-      block.call
-      Taro::Rails::ResponseValidation.call(self)
-    ensure
-      Taro::Types::BaseType.rendering = nil
-    end
-  end
-
-  def self.installed
-    @installed ||= {}
-  end
-
-  def self.call(controller)
-    declaration = Taro::Rails.declaration_for(controller)
-    nesting = declaration.return_nestings[controller.status]
-    expected = declaration.returns[controller.status]
-    if nesting
-      # case: `returns :some_nesting, type: 'SomeType'` (ad-hoc return type)
-      check_nesting(controller.response, nesting)
-      expected = expected.fields[nesting].type
-    end
-
-    check_expected_type_was_used(controller, expected)
-  end
-
-  def self.check_nesting(response, nesting)
-    return unless /json/.match?(response.media_type)
-
-    first_key = response.body.to_s[/\A{\s*"([^"]+)"/, 1]
-    first_key == nesting.to_s || raise(Taro::ResponseError, <<~MSG)
-      Expected response to be nested in "#{nesting}" key, but it was not.
-      (First JSON key in response: "#{first_key}".)
-    MSG
+  def self.install(controller_class:)
+    controller_class.prepend(self) if Taro.config.validate_response
   end
 
-  def self.check_expected_type_was_used(controller, expected)
-    used = Taro::Types::BaseType.rendering
-
-    if expected.nil?
-      raise(Taro::ResponseError, <<~MSG)
-        No matching return type declared in #{controller.class}##{controller.action_name}\
-        for status #{controller.status}.
-      MSG
+  def render(*, **kwargs, &)
+    result = super
+    if (declaration = Taro::Rails.declaration_for(self))
+      Taro::Rails::ResponseValidator.call(self, declaration, kwargs[:json])
     end
-
-    used&.<=(expected) || raise(Taro::ResponseError, <<~MSG)
-      Expected #{controller.class}##{controller.action_name} to use #{expected}.render,
-      but #{used ? "#{used}.render" : 'no type render method'} was called.
-    MSG
-
-    Taro::Types::BaseType.used_in_response = used # for comparisons in specs
+    result
   end
 end