Lots of new goodies Praxis 0.14

[Josep Blanquer]

All,

 We have just released a new Praxis gem (0.14) which comes jam-packed with new goodies. Here is the paste from the Changelog with the most salient additions:

0.14.0

• Adds features for customizing and exporting the Doc browser, namely the following changes:
  1. All doc browser stuff is now centralised under the praxis:docs namespace.
  2. The doc browser requires node.js. (TODO: add this to the docs PR)
  3. rake praxis:docs:generate generates the JSON schema files. rake praxis:api_docs is now an alias of this with the idea that rake praxis:api_docs will be deprecated.
  4. rake praxis:docs:preview will open a browser window with the doc browser. It will refresh automatically when the design files change as well as when any customisations change.
  5. rake praxis:docs:build will generate a fully built static version of the app in docs/output. This can then be put on S3 or GH pages and should work.
  6. The default app generator will now generate a docs directory with some files to get you started.
  7. Any .js file in the docs directory will be included in the doc browser. Angular's dependency injection allows users to override any service or controller as needed.
  8. The default docs/styles.scss simply @import 'praxis'. However this means the user can override any of bootstraps variables allowing for easy theme customisation. Rules etc. can now also be overridden.
  9. Any templates defined in docs/views take precedence over those defined in the doc browser. This means the user can easily customise parts of the app, while leaving the rest up to us.
  10. Any changes to the above customisations will be automatically reloaded on save.
• First pass at describing (and doc-generating) API global information
  • Inside a Praxis::ApiDefinition.define block one can now specify a few things about the API by using:
    • info("1.0") <block> - Which will apply to a particular version only
    • info <block> - Which will be inherited by any existing API version
    • The current pieces of information that can be defined in the block are: name, title, description andbasepath. See this for details
  • NOTE: This information is output to the JSON files, BUT not used in the doc browser yet.
• Changed the doc generation and browser to use "ids" instead of "names" for routes and generated files.
  • Currently, "ids" are generated using dashes instead of double colons (instead of random ids). This closes issue #31.
• Added the definition and handling of canonical urls for API resources
  • One can now specify which action URL should be considered as the canonical resource href:
    • by using canonical_path <action_name> at the top of the resource definition class
    • See the instances resource definition for an example.
  • With a canonical href defined, one can then both generate and parse them by using:
    • .to_href(<named arguments hash>) => <href String>
    • .parse_href( <href String> ) => < named arguments hash >. Note: The returned arguments are properly typed-coerced.
    • These helpers can be accessed from:
      • the definition object in the controller instance (i.e., `self.definition.to_href(id: 1). )
      • or through the class-level methods in the resource definition (i.e.MyApiResource.parse_href("/my_resource/1") )
• Hooked up rake tasks into the praxis binary for convenience. In particular
  • praxis routes [json]
  • praxis docs [browser]
  • praxis console
• Added MediaTypeCommon module, which contains the identifier, description, and describe methods formerly found in MediaType. This is now the module used for checking whether a given class should be included in generated documentation, or is valid for use in a ResponseDefinition
• Improved Praxis::Collection.of when used with MediaTypes
  • It will now define an inner <media_type>::Collection type that is an Attributor::Collection of the MediaType that also will include the MediaTypeCommon module.
  • By default, Praxis will take the identifier of the parent MediaType and append a collection=true suffix to it.
• Fixed ResponseDefinition Content-Type validation to properly handle parameters (i.e., "application/json;collection=true").
  • Note: For "index" type actions, this now means Praxis will properly validate any 'collection=true' parameter specified in the ResponseDefintion and set by the controller.
• Deprecated MediaTypeCollection. Please define separate classes and attributes for "collection" and "summary" uses.
• Improved code for stages
  • setup! is no longer called within the run default code of a stage
  • removed unnecessary raise error when substages are empty (while not common it can be possible, and totally valid)
• Add Response to supported classes in PluginConcern
• Fix doc generation to use ids for top-level types (rather than names) so they are correctly linkable.
• Doc Browser: Added support for Markdown rendering of descriptions (for resources, media_types, attributes, etc...)
• Added test framework for the doc browser. Run the tests with grunt test from lib/api_browser.
• Enhanced the praxis:docs:preview rake task with an optional port parameter
• Fixed praxis:routes rake task to support actions that do not have routes defined
• Added :source to ActionDefinition parameter descriptions with the value of either 'url' or 'query' to denote where the parameter is (typically) extracted from. Note: not currently shown in doc browser.

Thanks to everybody that contributed to this!

Cheers and happy Praxing,

Josep M.