Praxis v0.14.0 Release Notes
-
- โ Adds features for customizing and exporting the Doc browser, namely the following changes:
- All doc browser stuff is now centralised under the
praxis:docs
namespace. - The doc browser requires node.js. (TODO: add this to the docs PR)
rake praxis:docs:generate
generates the JSON schema files.rake praxis:api_docs
is now an alias of this with the idea thatrake praxis:api_docs
will be deprecated.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.rake praxis:docs:build
will generate a fully built static version of the app indocs/output
. This can then be put on S3 or GH pages and should work.- The default app generator will now generate a docs directory with some files to get you started.
- Any
.js
file in thedocs
directory will be included in the doc browser. Angular's dependency injection allows users to override any service or controller as needed. - 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. - 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. - Any changes to the above customisations will be automatically reloaded on save.
- All doc browser stuff is now centralised under the
- 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.
- Inside a
- ๐ 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")
)
- the
- 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 theidentifier
,description
, anddescribe
methods formerly found inMediaType
. This is now the module used for checking whether a given class should be included in generated documentation, or is valid for use in aResponseDefinition
- ๐ Improved
Praxis::Collection.of
when used with MediaTypes- It will now define an inner
<media_type>::Collection
type that is anAttributor::Collection
of the MediaType that also will include theMediaTypeCommon
module. - By default, Praxis will take the identifier of the parent
MediaType
and append acollection=true
suffix to it.
- It will now define an inner
- ๐ 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.
- Note: For "index" type actions, this now means Praxis will properly validate any 'collection=true' parameter specified in the
- ๐ Deprecated
MediaTypeCollection
. Please define separate classes and attributes for "collection" and "summary" uses. - ๐ Improved code for stages
setup!
is no longer called within therun
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 inPluginConcern
- ๐ 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
toActionDefinition
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.
- โ Adds features for customizing and exporting the Doc browser, namely the following changes: