« Changelog History


Praxis v0.17.0 Release Notes

    • 🔀 Merges action details pages into one long page in doc browser
    • Refined path-based versioning:
      • Added ApiGeneralInfo#version_with, which defaults to [:header, :params] and may be set to :path to use path-based versioning.
      • Added support for specifying an :api_version placeholder to the global version's ApiGeneralInfo#base_path.
      • Deprecated ResourceDefinition.version using: :path option, use ApiGeneralInfo#version_with instead.
    • 🛠 Fix bug where before/after hooks set on sub-stages of :app would not be triggered
    • 🔨 Refactors the api browser to allow registering custom type templates.
      • This also removes an undocumented feature that did something similar.
      • Fixes an issue where Struct properties wouldn't be displayed.
    • ➕ Added endpoint directive to global API info, only used for documentation purposes.
    • ➕ Added ResourceDefinition.parent directive to define a parent resource.
      • The parent's canonical_path is used as the base of the child's routes.
      • Any parameters in the parent's route will also be applied as defaults in the child. The last route parameter is assumed to be an 'id'-type parameter, and is prefixed with the parent's snake-cased singular name. I.e., id from a Volume parent will be renamed to volume_id. Any other parameters are copied unchanged.
      • This behavior can be overridden by providing a mapping hash of the form {parent_name => child_name} to the parent directive. See [VolumeSnapshots](spec/spec_app/design/resources/volume_snapshots.rb) for an example.
    • 🔨 Backwards incompatible Change: Refactored ValidationError to be more consistent with the reported fields
      • Changed message for summary. Always present, and should provide a quick description of the type of error encountered. For example: "Error loading payload data"
      • Semantically changed errors to always have the details of one or many errors that have occurred. For example: "Unknown key received: :foobar while loading \$.payload.user"
      • Note: if you are an application that used and tested against the previous message field you will need to adjust your tests to check for the values in the summary field and or the errors contents. But it will now be a much more consistent experience that will allow API clients to notify of the exact errors and details to their clients.
    • 👀 Added Application.validation_handler to customize response generation for validation errors. See [validation_handler.rb](lib/praxis/validation_handler.rb) for default version.
    • Copied mustermann's routers to praxis repo in anticipation of their removal from mustermann itself.
    • ➕ Added response body validation.
      • Validation is controlled by the praxis.validate_response_bodies boolean config option, and uses the media_type defined for the response definition.
    • ➕ Added location: option to Responses::Created.new.
    • 📜 ResourceDefinition.parse_href now accepts any instance of URI::Generic in addition to a string.
    • 🛠 Fixed path generation for nested ResourceDefinitions
    • Substantial changes and improvements to multipart request and response handling:
      • Added Praxis::Types::MultipartArray, a type of Attributor::Collection with Praxis::MultipartPart members that allows the handling of duplicate named parts and unnamed ones. The new type supports defining many details about the expected structure of the parts, including headers, payloads, names and filename information. In addition, this type is able to load and validate full multipart bodies into the expected type structure, generate example objects as well as dump them into a full multipart body including boundaries and properly encoded parts following their content-types. See documentation for details and more features.
      • Made Praxis::MultipartPart a proper Attributor::Type.
      • Added Praxis::Responses:MultipartOk properly returning MultipartArray responses.
      • Deprecated Praxis::Multipart. A replacement for true hash-like behavior will be added before their removal in 1.0.
    • ActionDefinition#response now accepts an optional second type parameter, and optional block to further define that type. The type provided will be used to specify the media_type option to pass to the corresponding ResponseDefinition.
    • 0️⃣ The header directive inside ActionDefinition#headers now accepts an optional second type parameter that may be used to override the default String type that would be used.
    • ➕ Added Praxis::Handlers::Plain encoder for 'text/plain'.
    • 🛠 Fixed Praxis::Handlers::XML handler to transform dashes to underscores and treat empty hashes like ActiveSupport does.
    • ➕ Adds hierarchival navigation to the doc browser.
    • ➕ Adds a ConfigurationProvider allowing for easy doc customization.