praxis 0.21 → 2.0.pre.3

Sign up to get free protection for your applications and to get access to all the features.
Files changed (102) hide show
  1. checksums.yaml +4 -4
  2. data/.travis.yml +8 -15
  3. data/CHANGELOG.md +328 -299
  4. data/CONTRIBUTING.md +4 -4
  5. data/README.md +11 -9
  6. data/lib/api_browser/app/js/directives/attribute_table.js +2 -1
  7. data/lib/api_browser/app/js/directives/conditional_requirements.js +13 -0
  8. data/lib/api_browser/app/js/directives/type_placeholder.js +10 -1
  9. data/lib/api_browser/app/js/factories/normalize_attributes.js +4 -2
  10. data/lib/api_browser/app/js/factories/template_for.js +5 -2
  11. data/lib/api_browser/app/js/filters/has_requirement.js +14 -0
  12. data/lib/api_browser/app/js/filters/tag_requirement.js +13 -0
  13. data/lib/api_browser/app/sass/praxis.scss +11 -0
  14. data/lib/api_browser/app/views/action.html +2 -2
  15. data/lib/api_browser/app/views/directives/attribute_description/member_options.html +2 -2
  16. data/lib/api_browser/app/views/directives/attribute_table.html +1 -1
  17. data/lib/api_browser/app/views/type.html +1 -1
  18. data/lib/api_browser/app/views/type/details.html +2 -2
  19. data/lib/api_browser/app/views/types/embedded/array.html +2 -0
  20. data/lib/api_browser/app/views/types/embedded/default.html +3 -1
  21. data/lib/api_browser/app/views/types/embedded/requirements.html +6 -0
  22. data/lib/api_browser/app/views/types/embedded/single_req.html +9 -0
  23. data/lib/api_browser/app/views/types/embedded/struct.html +14 -2
  24. data/lib/api_browser/app/views/types/standalone/array.html +1 -1
  25. data/lib/api_browser/app/views/types/standalone/struct.html +2 -1
  26. data/lib/api_browser/package.json +1 -1
  27. data/lib/praxis.rb +9 -3
  28. data/lib/praxis/action_definition.rb +1 -1
  29. data/lib/praxis/action_definition/headers_dsl_compiler.rb +1 -1
  30. data/lib/praxis/application.rb +1 -9
  31. data/lib/praxis/bootloader.rb +1 -4
  32. data/lib/praxis/config.rb +1 -1
  33. data/lib/praxis/dispatcher.rb +10 -6
  34. data/lib/praxis/docs/generator.rb +2 -1
  35. data/lib/praxis/extensions/attribute_filtering/active_record_filter_query_builder.rb +180 -0
  36. data/lib/praxis/extensions/attribute_filtering/filtering_params.rb +273 -0
  37. data/lib/praxis/extensions/attribute_filtering/sequel_filter_query_builder.rb +125 -0
  38. data/lib/praxis/extensions/field_selection.rb +1 -9
  39. data/lib/praxis/extensions/field_selection/active_record_query_selector.rb +51 -0
  40. data/lib/praxis/extensions/field_selection/sequel_query_selector.rb +61 -0
  41. data/lib/praxis/extensions/rails_compat.rb +2 -0
  42. data/lib/praxis/extensions/rails_compat/request_methods.rb +19 -0
  43. data/lib/praxis/handlers/xml.rb +1 -1
  44. data/lib/praxis/mapper/active_model_compat.rb +98 -0
  45. data/lib/praxis/mapper/resource.rb +242 -0
  46. data/lib/praxis/mapper/selector_generator.rb +149 -0
  47. data/lib/praxis/mapper/sequel_compat.rb +76 -0
  48. data/lib/praxis/media_type_identifier.rb +2 -1
  49. data/lib/praxis/middleware_app.rb +20 -2
  50. data/lib/praxis/multipart/parser.rb +14 -2
  51. data/lib/praxis/notifications.rb +1 -1
  52. data/lib/praxis/plugins/mapper_plugin.rb +64 -0
  53. data/lib/praxis/plugins/rails_plugin.rb +104 -0
  54. data/lib/praxis/request.rb +7 -1
  55. data/lib/praxis/request_superclassing.rb +11 -0
  56. data/lib/praxis/resource_definition.rb +5 -5
  57. data/lib/praxis/response.rb +1 -1
  58. data/lib/praxis/route.rb +1 -1
  59. data/lib/praxis/routing_config.rb +1 -1
  60. data/lib/praxis/trait.rb +1 -1
  61. data/lib/praxis/types/media_type_common.rb +2 -2
  62. data/lib/praxis/types/multipart.rb +1 -1
  63. data/lib/praxis/types/multipart_array.rb +2 -2
  64. data/lib/praxis/types/multipart_array/part_definition.rb +1 -1
  65. data/lib/praxis/version.rb +1 -1
  66. data/praxis.gemspec +14 -13
  67. data/spec/functional_spec.rb +4 -7
  68. data/spec/praxis/action_definition_spec.rb +1 -1
  69. data/spec/praxis/application_spec.rb +1 -1
  70. data/spec/praxis/collection_spec.rb +3 -2
  71. data/spec/praxis/config_spec.rb +2 -2
  72. data/spec/praxis/extensions/field_selection/active_record_query_selector_spec.rb +106 -0
  73. data/spec/praxis/extensions/field_selection/sequel_query_selector_spec.rb +147 -0
  74. data/spec/praxis/extensions/field_selection/support/spec_resources_active_model.rb +130 -0
  75. data/spec/praxis/extensions/field_selection/support/spec_resources_sequel.rb +106 -0
  76. data/spec/praxis/handlers/xml_spec.rb +2 -2
  77. data/spec/praxis/mapper/resource_spec.rb +169 -0
  78. data/spec/praxis/mapper/selector_generator_spec.rb +293 -0
  79. data/spec/praxis/media_type_spec.rb +0 -10
  80. data/spec/praxis/middleware_app_spec.rb +29 -9
  81. data/spec/praxis/request_stages/action_spec.rb +8 -1
  82. data/spec/praxis/response_definition_spec.rb +7 -4
  83. data/spec/praxis/response_spec.rb +1 -1
  84. data/spec/praxis/responses/internal_server_error_spec.rb +2 -2
  85. data/spec/praxis/responses/validation_error_spec.rb +2 -2
  86. data/spec/praxis/router_spec.rb +1 -1
  87. data/spec/spec_app/app/controllers/instances.rb +1 -1
  88. data/spec/spec_app/config/environment.rb +3 -21
  89. data/spec/spec_helper.rb +11 -15
  90. data/spec/support/be_deep_equal_matcher.rb +39 -0
  91. data/spec/support/spec_resources.rb +124 -0
  92. data/tasks/thor/templates/generator/empty_app/Gemfile +3 -3
  93. metadata +102 -77
  94. data/.ruby-version +0 -1
  95. data/lib/praxis/extensions/mapper_selectors.rb +0 -16
  96. data/lib/praxis/media_type_collection.rb +0 -127
  97. data/lib/praxis/plugins/praxis_mapper_plugin.rb +0 -246
  98. data/lib/praxis/stats.rb +0 -113
  99. data/spec/praxis/media_type_collection_spec.rb +0 -157
  100. data/spec/praxis/plugins/praxis_mapper_plugin_spec.rb +0 -142
  101. data/spec/praxis/stats_spec.rb +0 -9
  102. data/spec/spec_app/app/models/person.rb +0 -3
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: d0a0928d3b9a59294d32767a333b73c03a0a7955
4
- data.tar.gz: 840261c0c55f18280f3c32d53a62053ed8582834
3
+ metadata.gz: d869bce23150f16857b3d92fb1e4e6fe98b0b747
4
+ data.tar.gz: bf2e0bac5b872453a6ae142f518591a2fae67180
5
5
  SHA512:
6
- metadata.gz: 2c7d30737b31ec8204e030ca43577d8a4620b4a16ee3f9ec00c40ef740f08db8c7c21d9bc1d06dc7ddc56e2223dc0f9aaa990526a6f92f7297493dcf02158c11
7
- data.tar.gz: b1e794d55ef40a616c21adeb8a72cea53b796e4a943636c5a16a576f282298c6f573b730f708ab2a0bbb050784c56c3b1fe53f760488c3100d98958a2b50f6eb
6
+ metadata.gz: d2975bad774d35e3c7a98067442258fff5d7670f161ee4b5653dfe5b038f1af341b9fb21fefcff733d9f2a7c96a9ee742014919c29148d87826433b15291dcb0
7
+ data.tar.gz: cf8665de0a625dee430a30b23a07328bebd8d60cffb2aad9e7dc3aed9503c21afd463aa024ee97fefb7ce639db008716aa4996ee70e3361d91d102b5408c6adc
@@ -1,20 +1,13 @@
1
- language: ruby
2
- cache: bundler
3
1
  sudo: false
2
+ language: ruby
4
3
  rvm:
5
- - 2.2.5
6
- - 2.3.1
7
- node_js:
8
- - "0.10"
4
+ - 2.4
5
+ - 2.5
6
+ - 2.6
7
+ - 2.7
8
+ script:
9
+ - bundle exec rspec spec
9
10
  branches:
10
11
  only:
11
12
  - master
12
- before_install:
13
- - cd lib/api_browser
14
- - npm install
15
- - cd ../..
16
- script:
17
- - bundle exec rspec spec
18
- - cd lib/api_browser
19
- - npm test
20
- - cd ../..
13
+ - /.*/
@@ -1,237 +1,271 @@
1
1
  # Praxis Changelog
2
2
 
3
3
  ## next
4
+ - Reworked the field selection DB query generation to support full tree of eager loaded dependencies
5
+ - Built support for both ActiveRecord and Sequel gems
6
+ - Selected DB fields will include/map the defined resource properties and will always include any necessary fields on both sides of the joins for the given associations.
7
+ - Added a configurable option to enable debugging of those generated queries (through `Praxis::Application.instance.config.mapper.debug_queries=true`)
8
+
9
+ ## 2.0.pre.1
10
+
11
+ - Bring over partial functionality from praxis-mapper and remove dependency on same
12
+ - Praxis::Mapper's ::Resource and ::SelectorGenerator are now included
13
+ - General cleanup and simplification
14
+
15
+ ## 0.22.pre
16
+
17
+ - Builds an initial Rails embeddability/compatibility set of functions and helpers:
18
+ - Refactored dispatcher methods so that instrumentation can be easily added on (but without building a flexible hook system that might decrease the performance)
19
+ - Change `Praxis:Request` super classing to be definable by a module setter
20
+ - Make `rails_compat/request_methods` to use it.
21
+ - Built `rails_compat` extension. Which for now only:
22
+ - changes `Praxis:Request` to derive from `ActionDispatch::Request`
23
+ - Will load the RailsPlugin code
24
+ - Built a `RailsPlugin` plugin which, for now, will:
25
+ - emulate firing off the `action_controller` basic hooks (`start_processing` and `process_action`).
26
+ - Add a few basic controller methods (which make some of the other mixing you might want to throw in your controllers happier). For example: the `head` method for controllers, as it is one of the most used for simple extensions. NOTE: The `render` method is not currently added.
27
+ - NOTE: db and view runtime values on request processing not done (i.e., not integrated with Praxis’ DB or rendering frameworks)
28
+ - Include URI in the primitive types when generating docs and displaying them (as to not have a generic URI schema polluting the lists)
29
+ - Loosen up the version of Rack that Praxis requires. Adapted the old MultipartParser to be compabible with Rack 2x (but in reality we should see about reusing the brand new parser that 2x comes with in the future)
30
+ - Loosen up the version of Mustermann to allow for their latest 1.x series (which will be used by some of the latest gems with Rails 5 and friends)
31
+ - Fix and improve Doc Browser presentation
32
+ - proper showing of substructures of payloads
33
+ - mark required attrs with red star (and semi-required as orange)
34
+ - display the existing special requirements as well
35
+ - Added requirements for parameters as well (in addition to payload)
36
+ - format member_options display better
37
+ - Make `MiddleWareApp` initialize lazily. This allows the main rack app (i.e., Rails) to be fully initialized by the time any code in the Praxis middleware gets touched (i.e., full ActiveRecord connection initialization...etc.)
38
+ - Removed 'Stats' plugin
39
+ - CGI.decode filter values in the `FilteringParams` extension
4
40
 
5
41
  ## 0.21
6
42
 
7
- * Protect against `MediaType`s that do not have any links defined.
8
- * More robust scanning of existing types when generating docs. Some types might have not been
43
+ - Protect against `MediaType`s that do not have any links defined.
44
+ - More robust scanning of existing types when generating docs. Some types might have not been
9
45
  properly reported in the `schemas` section of the JSON docs if they were only used somewhere
10
46
  deep in some other type or action hierarchy
11
- * Build doc browser support for defining top-level home pages for types.
47
+ - Build doc browser support for defining top-level home pages for types.
12
48
  Apps can achieve the override by registering templates that respond to the ‘main’ type (instead of
13
49
  the other existing ‘label’,’embedded’ and ‘standalone’ modes).
14
- * Enhance doc browser to show header and location expectations on action responses that have them
50
+ - Enhance doc browser to show header and location expectations on action responses that have them
15
51
  defined
16
- * Allow Plugin registration without requiring config_key
17
- * registration will select a default config_key based on the class name
18
- * A new `documentation_url` global directive is exposed for authors to be able to
52
+ - Allow Plugin registration without requiring config_key
53
+ - registration will select a default config_key based on the class name
54
+ - A new `documentation_url` global directive is exposed for authors to be able to
19
55
  indicate where documentation will be hosted.
20
- * If this is provided, the default *validation handler* will add a `documentation`
56
+ - If this is provided, the default _validation handler_ will add a `documentation`
21
57
  key to the response pointing at a url that should correspond to the documentation
22
58
  for the resource the user was requesting.
23
- * `Praxis::Docs::LinkBuilder` can be used to generate these documentation urls from
59
+ - `Praxis::Docs::LinkBuilder` can be used to generate these documentation urls from
24
60
  the praxis application.
25
- * You can now switch your doc browser to use HTML5 style urls (i.e.
61
+ - You can now switch your doc browser to use HTML5 style urls (i.e.
26
62
  `/1.0/type/V1-MediaTypes-PriceFilter` instead of
27
63
  `/index.html#/1.0/type/V1-MediaTypes-PriceFilter`).
28
- * Remove deprecated rake tasks.
29
- * Remove some remaining inline styling in doc browser.
30
- * Adds a `ExampleProvider.removeHandlersForKey` call. You can use `ExampleProvider.removeHandlersForKey('general')`
64
+ - Remove deprecated rake tasks.
65
+ - Remove some remaining inline styling in doc browser.
66
+ - Adds a `ExampleProvider.removeHandlersForKey` call. You can use `ExampleProvider.removeHandlersForKey('general')`
31
67
  to get rid of the default example if required.
32
- * Make Traits accumulate block definitions for `params`,`headers` and `payload` rather than overriding them.
33
- * Switch to lazy evaluation of `base_params` from `ApiDefinition` to properly inherit them into the resources
68
+ - Make Traits accumulate block definitions for `params`,`headers` and `payload` rather than overriding them.
69
+ - Switch to lazy evaluation of `base_params` from `ApiDefinition` to properly inherit them into the resources
34
70
  and their corresponding actions even before the application's `MediaTtypes` have been finalized.
35
- * Built the `MiddlewareApp` class to make it easy to run a Praxis app mounted as an intercepting
71
+ - Built the `MiddlewareApp` class to make it easy to run a Praxis app mounted as an intercepting
36
72
  middleware which will only forward requests down the stack if they didn't match any of its routes.
37
- * Note: it properly skips forwarding when 404s are purposedly returned by the application itself.
38
- * Note2: it also respects the `X-Cascade=pass` conventions.
39
-
73
+ - Note: it properly skips forwarding when 404s are purposedly returned by the application itself.
74
+ - Note2: it also respects the `X-Cascade=pass` conventions.
40
75
 
41
76
  ## 0.20.1
42
77
 
43
- * Doc generation: handle SimpleMediaTypes so that they don’t show up in the generated schemas.
44
- * Ensure we require AS#Enumerable extension is loaded, which is required in the generator code.
45
- * Add Date to the list of primitive types so that it does not show in the generated schemas.
46
- * Enhance the `:created` response_template, so that it can take the associated media_type
47
- * Doc Browser: fix route display to have the captures instead of the example
78
+ - Doc generation: handle SimpleMediaTypes so that they don’t show up in the generated schemas.
79
+ - Ensure we require AS#Enumerable extension is loaded, which is required in the generator code.
80
+ - Add Date to the list of primitive types so that it does not show in the generated schemas.
81
+ - Enhance the `:created` response_template, so that it can take the associated media_type
82
+ - Doc Browser: fix route display to have the captures instead of the example
48
83
 
49
84
  ## 0.20.0
50
85
 
51
- * You can now add a `bower.json` file to your `docs` folder. Any dependencies
86
+ - You can now add a `bower.json` file to your `docs` folder. Any dependencies
52
87
  you list there will be included in the doc browser.
53
- * The Plugin API now exposes `Praxis::Plugin#register_doc_browser_plugin(path)`,
88
+ - The Plugin API now exposes `Praxis::Plugin#register_doc_browser_plugin(path)`,
54
89
  which allows plugins to register assets that will be included in the doc browser.
55
90
  This is a convenient way to share customizations and optional features amongst
56
91
  different API projects.
57
- * Fixes an issue where an odd scrollbar would appear in some cases in the doc browser.
58
- * Fixed a corner-case in doc generation which could omit certain existing MediaTypes
92
+ - Fixes an issue where an odd scrollbar would appear in some cases in the doc browser.
93
+ - Fixed a corner-case in doc generation which could omit certain existing MediaTypes
59
94
  (when these existed but there were never referenced in any other part of the app).
60
- * Added `ApiGeneralInfo` to supported modules a `PluginConcern` can extend.
61
- * Fixed `MediaType` support for attributor advanced requirements.
62
- * Doc Browser now exposes an API to register functions that generate code examples.
95
+ - Added `ApiGeneralInfo` to supported modules a `PluginConcern` can extend.
96
+ - Fixed `MediaType` support for attributor advanced requirements.
97
+ - Doc Browser now exposes an API to register functions that generate code examples.
63
98
  These can be registered with `ExamplesProvider.register` call.
64
99
 
65
100
  ## 0.19.0
66
101
 
67
- * Handle loading empty `MediaTypeIdentifier` values (to return `nil`)
68
- * Doc browser now displays examples for action responses.
69
- * Added `Controller#media_type` helper that returns the `media_type` defined
70
- for the current response, or defaults to the one defined by the controller's
71
- resource definition.
72
- * Added assorted extensions, all under the `Praxis::Extensions` module:
73
- * `FieldSelection` adds a new type, `Praxis::Extensions::FieldSelection::FieldSelector`
102
+ - Handle loading empty `MediaTypeIdentifier` values (to return `nil`)
103
+ - Doc browser now displays examples for action responses.
104
+ - Added `Controller#media_type` helper that returns the `media_type` defined
105
+ for the current response, or defaults to the one defined by the controller's
106
+ resource definition.
107
+ - Added assorted extensions, all under the `Praxis::Extensions` module:
108
+ - `FieldSelection` adds a new type, `Praxis::Extensions::FieldSelection::FieldSelector`
74
109
  that wraps the `Attributor::FieldSelector` type and improves the definition
75
110
  of parameters for a set of fields. Must be required explicitly from
76
111
  'praxis/extensions/field_selection'.
77
- * The parsed set of fields will be available as the `fields` accessor of
112
+ - The parsed set of fields will be available as the `fields` accessor of
78
113
  the loaded value.
79
- * For example, to define a parameter that should take a set of fields
114
+ - For example, to define a parameter that should take a set of fields
80
115
  for a `Person` media type, you would define a `:fields` attribute in the
81
116
  params like: `attribute :fields, FieldSelector.for(Person)`. The parsed
82
117
  fields in the request would then be available with
83
118
  `request.params.fields.fields`.
84
- * `Rendering` adds `render` and `display` helper methods to controllers to
85
- reduce common boilerplate in producing rendered representations of media types
86
- and setting response "Content-Type" headers.
87
- * `Controller#render(object, include_nil: false)` loads `object` into the
88
- the current applicable `MediaType` (as from `Controller#media_type`) and
89
- renders it using the fields provided by `Controller#expanded_fields` (from the
119
+ - `Rendering` adds `render` and `display` helper methods to controllers to
120
+ reduce common boilerplate in producing rendered representations of media types
121
+ and setting response "Content-Type" headers.
122
+ - `Controller#render(object, include_nil: false)` loads `object` into the
123
+ the current applicable `MediaType` (as from `Controller#media_type`) and
124
+ renders it using the fields provided by `Controller#expanded_fields` (from the
90
125
  `FieldExpansion` extension).
91
- * `Controller#display(object, include_nil: false)` calls `render` (above) with
126
+ - `Controller#display(object, include_nil: false)` calls `render` (above) with
92
127
  `object`, assigns the result to the current `response.body`, sets the
93
128
  response's "Content-Type" header to the appropriate MediaType identifier,
94
129
  and returns the response.
95
- * To use this extension, include it in a controller with
130
+ - To use this extension, include it in a controller with
96
131
  `include Praxis::Extensions::Rendering`.
97
- * `MapperSelectors` adds `Controller#set_selectors`, which sets selectors
132
+ - `MapperSelectors` adds `Controller#set_selectors`, which sets selectors
98
133
  in the controller's `identity_map` to ensure any fields and associations
99
134
  necessary to render the `:view` and/or `:fields` params specified in the
100
135
  request are loaded for a given model when `identity_map.load(model)` is called.
101
- * To use this extension, include it in a controller with
136
+ - To use this extension, include it in a controller with
102
137
  `include Praxis::Extensions::MapperSelectors`, and define `before`
103
138
  callbacks on relevant actions that call `set_selectors`. For example:
104
139
  `before actions: [:index, :show] { |controller| controller.set_selectors }`
105
- * `FieldExpansion` provides a `Controller#expanded_fields` helper for
106
- processing `:view` and/or `:fields` params to determine the final set fields
107
- necessary to handle the request.
108
- * Note: This is primarily an internal extension used by the `MapperSelectors`
109
- and `Rendering` extensions, and is automatically included by them.
110
- * A slew of Doc browser improvements:
111
- * Now uses the new JSON format for responses.
112
- * Traits now get exposed in the doc browser.
113
- * Now displays examples for requesting actions.
114
- * Now correctly displays top-level collections in action payloads.
115
- * Has improved scrolling for the sidebar.
116
- * Displays more detailed HTML titles.
117
- * Has been switched back to having a separate page per action, however actions are now shown in the sidebar.
118
- * Will now display multiply nested resources in a proper hierarchy.
119
- * Fix doc generator to only output versions in index for which we have resources (i.e. some can be nodoc!)
140
+ - `FieldExpansion` provides a `Controller#expanded_fields` helper for
141
+ processing `:view` and/or `:fields` params to determine the final set fields
142
+ necessary to handle the request.
143
+ - Note: This is primarily an internal extension used by the `MapperSelectors`
144
+ and `Rendering` extensions, and is automatically included by them.
145
+ - A slew of Doc browser improvements:
146
+ - Now uses the new JSON format for responses.
147
+ - Traits now get exposed in the doc browser.
148
+ - Now displays examples for requesting actions.
149
+ - Now correctly displays top-level collections in action payloads.
150
+ - Has improved scrolling for the sidebar.
151
+ - Displays more detailed HTML titles.
152
+ - Has been switched back to having a separate page per action, however actions are now shown in the sidebar.
153
+ - Will now display multiply nested resources in a proper hierarchy.
154
+ - Fix doc generator to only output versions in index for which we have resources (i.e. some can be nodoc!)
120
155
 
121
156
  ## 0.18.1
122
157
 
123
- * Fix Doc Browser regression, which would not show the schema in the Resource Definition home page.
158
+ - Fix Doc Browser regression, which would not show the schema in the Resource Definition home page.
124
159
 
125
160
  ## 0.18.0
126
161
 
127
- * Added `display_name` DSL to `ResourceDefinition` and `MediaType`
128
- * It is a purely informational field, mostly to be used by consumers of the generated docs
129
- * It defaults to the class name (stripping any of the prefix modules)
130
- * Revamped document generation to output a more compact format:
131
- * 1 file per api version: including info, resources, schemas and traits.
132
- * 1 single index file with global info plus just a list of version names
133
- * new task currently usable through `bundle exec rake praxis:docs:generate_beta`
134
- * NOTE: leaves the current doc generation tasks and code intact (until the doc browser is switched to use this)
135
- * Specialized `Multipart`’s family in its description to be ‘multipart’ instead of ‘hash’.
136
- * Added `Praxis::Handlers::FormData` for 'multipart/form-data'. Currently returns the input unchanged in `parse` and `generate`.
137
- * Added `Praxis::Handlers::WWWForm` for form-encoded data.
138
- * Added `Docs::Generator`, experimental new documentation generator. Use the `praxis:docs:experiments` rake task to generate. *Note*: not currently compatible with the documentation browser.
139
- * Added 'praxis.request_stage.execute' `ActiveSupport::Notifications` instrumentation to contorller action method execution in `RequestStages::Action#execute`.
140
- * Make action headers, params and payloads be required by default as it is probably what most people expect from it. To make any of those three definitions non-required, simply add the `:required` option as used in any other attribute definition. For example: `payload required: false do ...`
162
+ - Added `display_name` DSL to `ResourceDefinition` and `MediaType`
163
+ - It is a purely informational field, mostly to be used by consumers of the generated docs
164
+ - It defaults to the class name (stripping any of the prefix modules)
165
+ - Revamped document generation to output a more compact format:
166
+ - 1 file per api version: including info, resources, schemas and traits.
167
+ - 1 single index file with global info plus just a list of version names
168
+ - new task currently usable through `bundle exec rake praxis:docs:generate_beta`
169
+ - NOTE: leaves the current doc generation tasks and code intact (until the doc browser is switched to use this)
170
+ - Specialized `Multipart`’s family in its description to be ‘multipart’ instead of ‘hash’.
171
+ - Added `Praxis::Handlers::FormData` for 'multipart/form-data'. Currently returns the input unchanged in `parse` and `generate`.
172
+ - Added `Praxis::Handlers::WWWForm` for form-encoded data.
173
+ - Added `Docs::Generator`, experimental new documentation generator. Use the `praxis:docs:experiments` rake task to generate. _Note_: not currently compatible with the documentation browser.
174
+ - Added 'praxis.request_stage.execute' `ActiveSupport::Notifications` instrumentation to contorller action method execution in `RequestStages::Action#execute`.
175
+ - Make action headers, params and payloads be required by default as it is probably what most people expect from it. To make any of those three definitions non-required, simply add the `:required` option as used in any other attribute definition. For example: `payload required: false do ...`
141
176
 
142
177
  ## 0.17.1
143
178
 
144
- * Fixes an issue that would make exported documentation broken.
145
- * Fixes an issue that would make the version selector broken.
179
+ - Fixes an issue that would make exported documentation broken.
180
+ - Fixes an issue that would make the version selector broken.
146
181
 
147
182
  ## 0.17.0
148
183
 
149
- * Merges action details pages into one long page in doc browser
150
- * Refined path-based versioning:
151
- * Added `ApiGeneralInfo#version_with`, which defaults to `[:header, :params`] and may be set to `:path` to use path-based versioning.
152
- * Added support for specifying an `:api_version` placeholder to the global version's `ApiGeneralInfo#base_path`.
153
- * Deprecated `ResourceDefinition.version using: :path` option, use `ApiGeneralInfo#version_with` instead.
154
- * Fix bug where before/after hooks set on sub-stages of `:app` would not be triggered
155
- * Refactors the api browser to allow registering custom type templates.
156
- * This also removes an undocumented feature that did something similar.
157
- * Fixes an issue where Struct properties wouldn't be displayed.
158
- * Added `endpoint` directive to global API info, only used for documentation purposes.
159
- * Added `ResourceDefinition.parent` directive to define a parent resource.
160
- * The parent's `canonical_path` is used as the base of the child's routes.
161
- * 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.
162
- * 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.
163
- * Backwards incompatible Change: Refactored `ValidationError` to be more consistent with the reported fields
164
- * Changed `message` for `summary`. Always present, and should provide a quick description of the type of error encountered. For example: "Error loading payload data"
165
- * 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"
166
- * 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.
167
- * Added `Application.validation_handler` to customize response generation for validation errors. See [validation_handler.rb](lib/praxis/validation_handler.rb) for default version.
168
- * Copied mustermann's routers to praxis repo in anticipation of their removal from mustermann itself.
169
- * Added response body validation.
170
- * Validation is controlled by the `praxis.validate_response_bodies` boolean
171
- config option, and uses the `media_type` defined for the response definition.
172
- * Added `location:` option to `Responses::Created.new`.
173
- * `ResourceDefinition.parse_href` now accepts any instance of `URI::Generic` in addition to a string.
174
- * Fixed path generation for nested ResourceDefinitions
175
- * Substantial changes and improvements to multipart request and response handling:
176
- * 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.
177
- * Made `Praxis::MultipartPart` a proper `Attributor::Type`.
178
- * Added `Praxis::Responses:MultipartOk` properly returning `MultipartArray` responses.
179
- * Deprecated `Praxis::Multipart`. A replacement for true hash-like behavior will be added before their removal in 1.0.
180
- * `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`.
181
- * 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.
182
- * Added `Praxis::Handlers::Plain` encoder for 'text/plain'.
183
- * Fixed `Praxis::Handlers::XML ` handler to transform dashes to underscores and treat empty hashes like ActiveSupport does.
184
- * Adds hierarchival navigation to the doc browser.
185
- * Adds a ConfigurationProvider allowing for easy doc customization.
186
-
184
+ - Merges action details pages into one long page in doc browser
185
+ - Refined path-based versioning:
186
+ - Added `ApiGeneralInfo#version_with`, which defaults to `[:header, :params`] and may be set to `:path` to use path-based versioning.
187
+ - Added support for specifying an `:api_version` placeholder to the global version's `ApiGeneralInfo#base_path`.
188
+ - Deprecated `ResourceDefinition.version using: :path` option, use `ApiGeneralInfo#version_with` instead.
189
+ - Fix bug where before/after hooks set on sub-stages of `:app` would not be triggered
190
+ - Refactors the api browser to allow registering custom type templates.
191
+ - This also removes an undocumented feature that did something similar.
192
+ - Fixes an issue where Struct properties wouldn't be displayed.
193
+ - Added `endpoint` directive to global API info, only used for documentation purposes.
194
+ - Added `ResourceDefinition.parent` directive to define a parent resource.
195
+ - The parent's `canonical_path` is used as the base of the child's routes.
196
+ - 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.
197
+ - 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.
198
+ - Backwards incompatible Change: Refactored `ValidationError` to be more consistent with the reported fields
199
+ - Changed `message` for `summary`. Always present, and should provide a quick description of the type of error encountered. For example: "Error loading payload data"
200
+ - 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"
201
+ - 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.
202
+ - Added `Application.validation_handler` to customize response generation for validation errors. See [validation_handler.rb](lib/praxis/validation_handler.rb) for default version.
203
+ - Copied mustermann's routers to praxis repo in anticipation of their removal from mustermann itself.
204
+ - Added response body validation.
205
+ - Validation is controlled by the `praxis.validate_response_bodies` boolean
206
+ config option, and uses the `media_type` defined for the response definition.
207
+ - Added `location:` option to `Responses::Created.new`.
208
+ - `ResourceDefinition.parse_href` now accepts any instance of `URI::Generic` in addition to a string.
209
+ - Fixed path generation for nested ResourceDefinitions
210
+ - Substantial changes and improvements to multipart request and response handling:
211
+ - 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.
212
+ - Made `Praxis::MultipartPart` a proper `Attributor::Type`.
213
+ - Added `Praxis::Responses:MultipartOk` properly returning `MultipartArray` responses.
214
+ - Deprecated `Praxis::Multipart`. A replacement for true hash-like behavior will be added before their removal in 1.0.
215
+ - `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`.
216
+ - 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.
217
+ - Added `Praxis::Handlers::Plain` encoder for 'text/plain'.
218
+ - Fixed `Praxis::Handlers::XML` handler to transform dashes to underscores and treat empty hashes like ActiveSupport does.
219
+ - Adds hierarchival navigation to the doc browser.
220
+ - Adds a ConfigurationProvider allowing for easy doc customization.
187
221
 
188
222
  ## 0.16.1
189
223
 
190
- * Fixed a bug where documentation generation would fail if an application had headers in a Trait using the simplified `header` DSL.
224
+ - Fixed a bug where documentation generation would fail if an application had headers in a Trait using the simplified `header` DSL.
191
225
 
192
226
  ## 0.16.0
193
227
 
194
- * Overhauled traits: they're now represented by a `Trait` class, which are created from `ApiDefinition#trait`.
195
- * `ApiDefinition#describe` will also include details of the defined traits.
196
- * `ResourceDefinition#describe` and `ActionDefinition#describe` will also include the names of the used traits.
197
- * *Note*: this may break some existing trait use cases, as they are now more-defined in their behavior, rather than simply stored blocks that are `instance_eval`-ed on the target.
198
- * Deprecated `ResourceDefinition.routing`. Use `ResourceDefinition.prefix` to define resource-level route prefixes instead.
199
- * Significantly refactored route generation.
200
- * The `base_path` property defined in `ApiDefinition#info` will now appear in the routing paths 'base' (instead of simply being used for documentation purposes).
201
- *Note*: unlike other info at that level, a global (unversioned) `base_path` is *not* overriden by specific version, rather the specific version's path is appended to the global path.
202
- * Any prefixes set on a `ResourceDefinition` or inside a `routing` block of an ActionDefinition are now additive. For example:
203
- * Setting a "/myresource" prefix in a "MyResource" definition, and setting a "/myaction" prefix within an action of that resource definition will result in a route containing the following segments ".../myresource/myaction...".
204
- * Prefixes can be equally set by including `Traits`, which will follow exactly the same additive rules.
205
- * To break the additive nature of the prefixes one can use a couple of different options:
206
- * Define the action route path with "//" to make it absolute, i.e. a path like "//people" would not include any defined prefix.
207
- * Explicitly clear the prefix by setting the prefix to `''` or `'//'`.
208
- * Added `base_params` to `ApiDefinition#info` as a way to share common action params
209
- * `base_params` may be defined for a specific Api version, which will make sharing params across all Resource definitions of that version)
210
- * or `base_params` may be defined in the Global Api section, which will make the parameters shared across all actions of all defined Api versions.
211
- * Fixed `MediaType#describe` to include the correct string representation of its identifier.
212
- * Allow route options to be passed to the underlying router (i.e. Mustermann at the moment)
213
- * routes defined in the `routing` blocks can now take any extra options which will be passed down to the Mustermann routing engine. Unknown options will be ignored!
214
- * Displaying routes (`praxis routes` or `rake praxis:routes`) will now include any options defined in a route.
215
- * Added an example on the instances resource of the embedded spec_app to show how to use the advanced `*` pattern and the `:except` Mustermann options (along with the required `:splat` attribute).
216
- * Spruced up the example app (generator) to use the latest `prefix` and `trait` changes
228
+ - Overhauled traits: they're now represented by a `Trait` class, which are created from `ApiDefinition#trait`.
229
+ - `ApiDefinition#describe` will also include details of the defined traits.
230
+ - `ResourceDefinition#describe` and `ActionDefinition#describe` will also include the names of the used traits.
231
+ - _Note_: this may break some existing trait use cases, as they are now more-defined in their behavior, rather than simply stored blocks that are `instance_eval`-ed on the target.
232
+ - Deprecated `ResourceDefinition.routing`. Use `ResourceDefinition.prefix` to define resource-level route prefixes instead.
233
+ - Significantly refactored route generation.
234
+ - The `base_path` property defined in `ApiDefinition#info` will now appear in the routing paths 'base' (instead of simply being used for documentation purposes).
235
+ _Note_: unlike other info at that level, a global (unversioned) `base_path` is _not_ overriden by specific version, rather the specific version's path is appended to the global path.
236
+ - Any prefixes set on a `ResourceDefinition` or inside a `routing` block of an ActionDefinition are now additive. For example:
237
+ - Setting a "/myresource" prefix in a "MyResource" definition, and setting a "/myaction" prefix within an action of that resource definition will result in a route containing the following segments ".../myresource/myaction...".
238
+ - Prefixes can be equally set by including `Traits`, which will follow exactly the same additive rules.
239
+ - To break the additive nature of the prefixes one can use a couple of different options:
240
+ - Define the action route path with "//" to make it absolute, i.e. a path like "//people" would not include any defined prefix.
241
+ - Explicitly clear the prefix by setting the prefix to `''` or `'//'`.
242
+ - Added `base_params` to `ApiDefinition#info` as a way to share common action params
243
+ - `base_params` may be defined for a specific Api version, which will make sharing params across all Resource definitions of that version)
244
+ - or `base_params` may be defined in the Global Api section, which will make the parameters shared across all actions of all defined Api versions.
245
+ - Fixed `MediaType#describe` to include the correct string representation of its identifier.
246
+ - Allow route options to be passed to the underlying router (i.e. Mustermann at the moment)
247
+ - routes defined in the `routing` blocks can now take any extra options which will be passed down to the Mustermann routing engine. Unknown options will be ignored!
248
+ - Displaying routes (`praxis routes` or `rake praxis:routes`) will now include any options defined in a route.
249
+ - Added an example on the instances resource of the embedded spec_app to show how to use the advanced `*` pattern and the `:except` Mustermann options (along with the required `:splat` attribute).
250
+ - Spruced up the example app (generator) to use the latest `prefix` and `trait` changes
217
251
 
218
252
  ## 0.15.0
219
253
 
220
- * Fixed handling of no app or design file groups defined in application layout.
221
- * Handled and added warning message for doc generation task when no routing block is defined for an action.
222
- * Improved `link` method in `MediaType` attribute definition to support inheriting the type from the `:using` option if if that specifies an attribute. For example: `link :posts, using: :posts_summary` would use the type of the `:posts_summary` attribute.
223
- * Fixed generated `Links` accessors to properly load the returned value.
224
- * Added `MediaTypeIdentifier` class to parse and manipulate Content-Type headers and Praxis::MediaType identifiers.
225
- * Created a registry for media type handlers that parse and generate document bodies with formats other than JSON.
226
- * Given a structured-data response, Praxis will convert it to JSON, XML or other formats based on the handler indicated by its Content-Type.
227
- * Given a request, Praxis will use the handler indicated by its Content-Type header to parse the body into structured data.
228
- * Fixed bug allowing "praxis new" to work when Praxis is installed as a system (non-bundled) gem.
229
- * Fixed doc generation code for custom types
230
- * Hardened Multipart type loading
254
+ - Fixed handling of no app or design file groups defined in application layout.
255
+ - Handled and added warning message for doc generation task when no routing block is defined for an action.
256
+ - Improved `link` method in `MediaType` attribute definition to support inheriting the type from the `:using` option if if that specifies an attribute. For example: `link :posts, using: :posts_summary` would use the type of the `:posts_summary` attribute.
257
+ - Fixed generated `Links` accessors to properly load the returned value.
258
+ - Added `MediaTypeIdentifier` class to parse and manipulate Content-Type headers and Praxis::MediaType identifiers.
259
+ - Created a registry for media type handlers that parse and generate document bodies with formats other than JSON.
260
+ - Given a structured-data response, Praxis will convert it to JSON, XML or other formats based on the handler indicated by its Content-Type.
261
+ - Given a request, Praxis will use the handler indicated by its Content-Type header to parse the body into structured data.
262
+ - Fixed bug allowing "praxis new" to work when Praxis is installed as a system (non-bundled) gem.
263
+ - Fixed doc generation code for custom types
264
+ - Hardened Multipart type loading
231
265
 
232
266
  ## 0.14.0
233
267
 
234
- * Adds features for customizing and exporting the Doc browser, namely the following changes:
268
+ - Adds features for customizing and exporting the Doc browser, namely the following changes:
235
269
  1. All doc browser stuff is now centralised under the `praxis:docs` namespace.
236
270
  2. The doc browser requires node.js. (TODO: add this to the docs PR)
237
271
  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.
@@ -242,163 +276,158 @@ config option, and uses the `media_type` defined for the response definition.
242
276
  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.
243
277
  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.
244
278
  10. Any changes to the above customisations will be automatically reloaded on save.
245
- * First pass at describing (and doc-generating) API global information
246
- * Inside a `Praxis::ApiDefinition.define` block one can now specify a few things about the API by using:
247
- * info("1.0") `<block>` - Which will apply to a particular version only
248
- * info `<block>` - Which will be inherited by any existing API version
249
- * The current pieces of information that can be defined in the block are: `name`, `title`, `description` and `basepath`. See [this](https://github.com/rightscale/praxis/blob/master/spec/spec_app/design/api.rb) for details
250
- * NOTE: This information is output to the JSON files, BUT not used in the doc browser yet.
251
- * Changed the doc generation and browser to use "ids" instead of "names" for routes and generated files.
252
- * Currently, "ids" are generated using dashes instead of double colons (instead of random ids). This closes issue #31.
253
- * Added the definition and handling of canonical urls for API resources
254
- * One can now specify which action URL should be considered as the canonical resource href:
255
- * by using `canonical_path <action_name>` at the top of the resource definition class
256
- * See the [instances](https://github.com/rightscale/praxis/blob/master/spec/spec_app/design/resources/instances.rb) resource definition for an example.
257
- * With a canonical href defined, one can then both generate and parse them by using:
258
- * `.to_href(<named arguments hash>) => <href String>`
259
- * `.parse_href( <href String> ) => < named arguments hash >`. Note: The returned arguments are properly typed-coerced.
260
- * These helpers can be accessed from:
261
- * the `definition` object in the controller instance (i.e., `self.definition.to_href(id: 1). )
262
- * or through the class-level methods in the resource definition (i.e. `MyApiResource.parse_href("/my_resource/1")` )
263
- * Hooked up rake tasks into the `praxis` binary for convenience. In particular
264
- * praxis routes [json]
265
- * praxis docs [browser]
266
- * praxis console
267
- * 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`
268
- * Improved `Praxis::Collection.of` when used with MediaTypes
269
- * 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.
270
- * By default, Praxis will take the identifier of the parent `MediaType` and append a `collection=true` suffix to it.
271
- * Fixed `ResponseDefinition` Content-Type validation to properly handle parameters (i.e., "application/json;collection=true").
272
- * 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.
273
- * Deprecated `MediaTypeCollection`. Please define separate classes and attributes for "collection" and "summary" uses.
274
- * Improved code for stages
275
- * `setup!` is no longer called within the `run` default code of a stage
276
- * removed unnecessary raise error when substages are empty (while not common it can be possible, and totally valid)
277
- * Add `Response` to supported classes in `PluginConcern`
278
- * Fix doc generation to use `ids` for top-level types (rather than names) so they are correctly linkable.
279
- * Doc Browser: Added support for Markdown rendering of descriptions (for resources, media_types, attributes, etc...)
280
- * Added test framework for the doc browser. Run the tests with `grunt test` from lib/api_browser.
281
- * Enhanced the `praxis:docs:preview` rake task with an optional port parameter
282
- * Fixed praxis:routes rake task to support actions that do not have routes defined
283
- * 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.
279
+ - First pass at describing (and doc-generating) API global information
280
+ - Inside a `Praxis::ApiDefinition.define` block one can now specify a few things about the API by using:
281
+ - info("1.0") `<block>` - Which will apply to a particular version only
282
+ - info `<block>` - Which will be inherited by any existing API version
283
+ - The current pieces of information that can be defined in the block are: `name`, `title`, `description` and `basepath`. See [this](https://github.com/rightscale/praxis/blob/master/spec/spec_app/design/api.rb) for details
284
+ - NOTE: This information is output to the JSON files, BUT not used in the doc browser yet.
285
+ - Changed the doc generation and browser to use "ids" instead of "names" for routes and generated files.
286
+ - Currently, "ids" are generated using dashes instead of double colons (instead of random ids). This closes issue #31.
287
+ - Added the definition and handling of canonical urls for API resources
288
+ - One can now specify which action URL should be considered as the canonical resource href:
289
+ - by using `canonical_path <action_name>` at the top of the resource definition class
290
+ - See the [instances](https://github.com/rightscale/praxis/blob/master/spec/spec_app/design/resources/instances.rb) resource definition for an example.
291
+ - With a canonical href defined, one can then both generate and parse them by using:
292
+ - `.to_href(<named arguments hash>) => <href String>`
293
+ - `.parse_href( <href String> ) => < named arguments hash >`. Note: The returned arguments are properly typed-coerced.
294
+ - These helpers can be accessed from:
295
+ - the `definition` object in the controller instance (i.e., `self.definition.to_href(id: 1). )
296
+ - or through the class-level methods in the resource definition (i.e. `MyApiResource.parse_href("/my_resource/1")` )
297
+ - Hooked up rake tasks into the `praxis` binary for convenience. In particular
298
+ - praxis routes [json]
299
+ - praxis docs [browser]
300
+ - praxis console
301
+ - 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`
302
+ - Improved `Praxis::Collection.of` when used with MediaTypes
303
+ - 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.
304
+ - By default, Praxis will take the identifier of the parent `MediaType` and append a `collection=true` suffix to it.
305
+ - Fixed `ResponseDefinition` Content-Type validation to properly handle parameters (i.e., "application/json;collection=true").
306
+ - 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.
307
+ - Deprecated `MediaTypeCollection`. Please define separate classes and attributes for "collection" and "summary" uses.
308
+ - Improved code for stages
309
+ - `setup!` is no longer called within the `run` default code of a stage
310
+ - removed unnecessary raise error when substages are empty (while not common it can be possible, and totally valid)
311
+ - Add `Response` to supported classes in `PluginConcern`
312
+ - Fix doc generation to use `ids` for top-level types (rather than names) so they are correctly linkable.
313
+ - Doc Browser: Added support for Markdown rendering of descriptions (for resources, media_types, attributes, etc...)
314
+ - Added test framework for the doc browser. Run the tests with `grunt test` from lib/api_browser.
315
+ - Enhanced the `praxis:docs:preview` rake task with an optional port parameter
316
+ - Fixed praxis:routes rake task to support actions that do not have routes defined
317
+ - 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.
284
318
 
285
319
  ## 0.13.0
286
- * Added `nodoc!` method to `ActionDefinition`, `ResourceDefinition` to hide actions and resources from the generated documentation.
287
- * Default HTTP responses:
288
- * Added descriptions
289
- * Added 408 RequestTimeout response
290
- * Replaced Ruport dependency in `praxis:routes` rake task with TerminalTable.
291
- * Fixed doc browser issue when attributes defaulting to false wouldn't display the default section.
292
- * Enhanced several logging aspects of the PraxisMapper plugin:
293
- * The log-level of the stats is now configurable in the plugin (see the comments [here](https://github.com/rightscale/praxis/blob/master/lib/praxis/plugins/praxis_mapper_plugin.rb) for details)
294
- * Added a "silence_mapper_stats" attribute in the Request objects so, actions and/or controllers can selectively skip logging stats (for example, health check controllers, etc)
295
- * It now logs a compact message (with the same heading) when the identity map has had no interactions.
296
- * Added X-Cascade header support
297
- * Configured with boolean `praxis.x_cascade` that defaults to true.
298
- * When enabled, Praxis will add an 'X-Cascade: pass' header to the response when the request was not routable to an action. It is not added if the action explicitly returns a `NotFound` response.
299
- * Fixed bug in request handling where `after` callbacks were being executed, even if the stage returned a response.
300
- * Added a handy option to tie an action route to match any HTTP verb.
301
- * Simply use `any` as the verb when you define it (i.e. any '/things/:id' )
302
- * Allow a MediaType to define a custom `links` attribute like any other.
303
- * This is not compatible if it also wants to use the `links` DSL.
304
-
305
320
 
321
+ - Added `nodoc!` method to `ActionDefinition`, `ResourceDefinition` to hide actions and resources from the generated documentation.
322
+ - Default HTTP responses:
323
+ - Added descriptions
324
+ - Added 408 RequestTimeout response
325
+ - Replaced Ruport dependency in `praxis:routes` rake task with TerminalTable.
326
+ - Fixed doc browser issue when attributes defaulting to false wouldn't display the default section.
327
+ - Enhanced several logging aspects of the PraxisMapper plugin:
328
+ - The log-level of the stats is now configurable in the plugin (see the comments [here](https://github.com/rightscale/praxis/blob/master/lib/praxis/plugins/praxis_mapper_plugin.rb) for details)
329
+ - Added a "silence_mapper_stats" attribute in the Request objects so, actions and/or controllers can selectively skip logging stats (for example, health check controllers, etc)
330
+ - It now logs a compact message (with the same heading) when the identity map has had no interactions.
331
+ - Added X-Cascade header support
332
+ - Configured with boolean `praxis.x_cascade` that defaults to true.
333
+ - When enabled, Praxis will add an 'X-Cascade: pass' header to the response when the request was not routable to an action. It is not added if the action explicitly returns a `NotFound` response.
334
+ - Fixed bug in request handling where `after` callbacks were being executed, even if the stage returned a response.
335
+ - Added a handy option to tie an action route to match any HTTP verb.
336
+ - Simply use `any` as the verb when you define it (i.e. any '/things/:id' )
337
+ - Allow a MediaType to define a custom `links` attribute like any other.
338
+ - This is not compatible if it also wants to use the `links` DSL.
306
339
 
307
340
  ## 0.11.2
308
341
 
309
- * The Doc Browser will now not change the menu when refreshing.
310
- * Fixes an issue where URLs in the doc browser would display JSON.
311
- * Fixes an issue where table columns in the doc browser would be overlapping.
312
- * Refactor Praxis Mapper plugin to be more generic.
313
- * Update attributor dependency to 2.4.0
342
+ - The Doc Browser will now not change the menu when refreshing.
343
+ - Fixes an issue where URLs in the doc browser would display JSON.
344
+ - Fixes an issue where table columns in the doc browser would be overlapping.
345
+ - Refactor Praxis Mapper plugin to be more generic.
346
+ - Update attributor dependency to 2.4.0
314
347
 
315
348
  ## 0.11.1
316
349
 
317
- * Fix `Stats` plugin to handle empty `args` hashes.
350
+ - Fix `Stats` plugin to handle empty `args` hashes.
318
351
 
319
352
  ## 0.11
320
353
 
321
- * `MediaTypeCollection`:
322
- * Added support for loading `decorate`ed `Resource` associations.
323
- * Refined and enhanced support for API versioning:
324
- * version DSL now can take a `using` option which specifies and array of the methods are allowed: `:header`,`:params`,`:path`(new)
325
- * if not specified, it will default to `using: [:header, :params]` (so that the version can be passed to the header OR the params)
326
- * the new `:path` option will build the action routes by prefixing the version given a common pattern (i.e., "/v1.0/...")
327
- * The effects of path versioning will be visible through `rake praxis:routes`
328
- * the default api prefix pattern is ("/v(version)/") but can changed by either
329
- * overriding ``Praxis::Request.path_version_prefix` and return the appropriate string prefix (i.e., by default this returns "/v")
330
- * or overriding `Praxis::Request.path_version_matcher` and providing the fully custom matching regexp. This regexp must have a capture (named `version`) that would return matched version value.
331
- * Enhanced praxis generator:
332
- * Added a new generator (available through `praxis new app_name`) which creates a blank new app, with enough basic structure and setup to start building an API.
333
- * Changed the example hello world generation command. Instead of `praxis generate app_name`, it is now available through `praxis example app_name`
334
- * Changed the path lookup for the praxis directory (to not use installed gems, which could be multiple). [Issue #67]
335
- * `ResourceDefinition`:
336
- * Added: `action_defaults` method, to define default options for actions. May be called more than once.
337
- * Removed: `params`, `payload`, `headers`, and `response`. Specify these inside `action_defaults` instead.
338
- * `Application`:
339
- * Added `middleware` method to use Rack middleware.
340
- * `ErrorHandler`
341
- * It is now possible to register the error handler class to be invoked when an uncaught exception is thrown by setting `Application#error_handler`.
342
- * The default error handler writes the error and backtrace into the Praxis logger, and returns an `InternalServerError` response
343
- * Added `Praxis::Notifications` framework backed by ActiveSupport::Notifications
344
- * Its interface is the same as AS::Notifications (.publish, .instrument, .subscribe, and etc.)
345
- * Each incoming rack request is instrumented as `rack.request.all`, with a payload of `{response: response}`, where `response` is the `Response` object that will be returned to the client. Internally, Praxis subscribes to this to generate timing statistics with `Praxis::Stats`.
346
- * Additionally, each request that is dispatched to an action is instrumented as `praxis.request.all`, with a payload of `{request: request, response: response}`, where `response` is as above, and `request` is the `Request` object for the request.
347
- * Added `Praxis::Stats` framework backed by `Harness` (i.e. a statsd interface)
348
- * Can be configured with a collector type (fake, Statsd) and an asynchronous queue + thread
349
- * Wraps the statsd interface: count, increment, decrement, time ...
350
- * Added a new `decorate_docs` method to enhance generated JSON docs for actions in `ResourceDefinitions`
351
- * Using this hook, anybody can register a block that can change/enhance the JSON structure of generated documents for any given action
352
- * Added a brand new Plugins architecture
353
- * Plugins can easily inject code in the Request, Controller, ResourceDefinition or ActionDefinition
354
- * Can be instances or singletons (and will be initialized correspondingly)
355
- * Plugins can be easily configured under a unique "config key" in the Praxis config
356
- * See the [Plugins](http://praxis-framework.io/reference/plugins/) section in the documentation for more information.
357
- * Added a Plugin for using the Praxis::Mapper gem
358
- * Configurable through a simple `praxis_mapper.yml` file
359
- * Its supports several repositories (by name)
360
- * Each repository can be of a different type (default is sequel)
361
- * `praxis:doc_browser` rake task now takes a port argument for specifying the port to run on, e.g. `rake praxis:doc_browser[9000]` to run on port 9000.
362
- * Added `show_exceptions` configuration option to to control default ErrorHandler behavior.
354
+ - `MediaTypeCollection`:
355
+ - Added support for loading `decorate`ed `Resource` associations.
356
+ - Refined and enhanced support for API versioning:
357
+ - version DSL now can take a `using` option which specifies and array of the methods are allowed: `:header`,`:params`,`:path`(new)
358
+ - if not specified, it will default to `using: [:header, :params]` (so that the version can be passed to the header OR the params)
359
+ - the new `:path` option will build the action routes by prefixing the version given a common pattern (i.e., "/v1.0/...")
360
+ - The effects of path versioning will be visible through `rake praxis:routes`
361
+ - the default api prefix pattern is ("/v(version)/") but can changed by either
362
+ - overriding ``Praxis::Request.path_version_prefix` and return the appropriate string prefix (i.e., by default this returns "/v")
363
+ - or overriding `Praxis::Request.path_version_matcher` and providing the fully custom matching regexp. This regexp must have a capture (named `version`) that would return matched version value.
364
+ - Enhanced praxis generator:
365
+ - Added a new generator (available through `praxis new app_name`) which creates a blank new app, with enough basic structure and setup to start building an API.
366
+ - Changed the example hello world generation command. Instead of `praxis generate app_name`, it is now available through `praxis example app_name`
367
+ - Changed the path lookup for the praxis directory (to not use installed gems, which could be multiple). [Issue #67]
368
+ - `ResourceDefinition`:
369
+ - Added: `action_defaults` method, to define default options for actions. May be called more than once.
370
+ - Removed: `params`, `payload`, `headers`, and `response`. Specify these inside `action_defaults` instead.
371
+ - `Application`:
372
+ - Added `middleware` method to use Rack middleware.
373
+ - `ErrorHandler`
374
+ - It is now possible to register the error handler class to be invoked when an uncaught exception is thrown by setting `Application#error_handler`.
375
+ - The default error handler writes the error and backtrace into the Praxis logger, and returns an `InternalServerError` response
376
+ - Added `Praxis::Notifications` framework backed by ActiveSupport::Notifications
377
+ - Its interface is the same as AS::Notifications (.publish, .instrument, .subscribe, and etc.)
378
+ - Each incoming rack request is instrumented as `rack.request.all`, with a payload of `{response: response}`, where `response` is the `Response` object that will be returned to the client. Internally, Praxis subscribes to this to generate timing statistics with `Praxis::Stats`.
379
+ - Additionally, each request that is dispatched to an action is instrumented as `praxis.request.all`, with a payload of `{request: request, response: response}`, where `response` is as above, and `request` is the `Request` object for the request.
380
+ - Added `Praxis::Stats` framework backed by `Harness` (i.e. a statsd interface)
381
+ - Can be configured with a collector type (fake, Statsd) and an asynchronous queue + thread
382
+ - Wraps the statsd interface: count, increment, decrement, time ...
383
+ - Added a new `decorate_docs` method to enhance generated JSON docs for actions in `ResourceDefinitions`
384
+ - Using this hook, anybody can register a block that can change/enhance the JSON structure of generated documents for any given action
385
+ - Added a brand new Plugins architecture
386
+ - Plugins can easily inject code in the Request, Controller, ResourceDefinition or ActionDefinition
387
+ - Can be instances or singletons (and will be initialized correspondingly)
388
+ - Plugins can be easily configured under a unique "config key" in the Praxis config
389
+ - See the [Plugins](http://praxis-framework.io/reference/plugins/) section in the documentation for more information.
390
+ - Added a Plugin for using the Praxis::Mapper gem
391
+ - Configurable through a simple `praxis_mapper.yml` file
392
+ - Its supports several repositories (by name)
393
+ - Each repository can be of a different type (default is sequel)
394
+ - `praxis:doc_browser` rake task now takes a port argument for specifying the port to run on, e.g. `rake praxis:doc_browser[9000]` to run on port 9000.
395
+ - Added `show_exceptions` configuration option to to control default ErrorHandler behavior.
363
396
 
364
397
  ## 0.10.0
365
398
 
366
- * Avoid loading responses (and templates) lazily as they need to be registered in time
367
- * Fix: app generator's handling of 404. [@magneland](https://github.com/magneland) [Issue #10](https://github.com/rightscale/praxis/issues/10)
368
- * Fix: Getting started doc. [@WilliamSnyders](https://github.com/WilliamSnyders) [Issue #19](https://github.com/rightscale/praxis/issues/19)
369
- * Controller filters can now shortcut the request lifecycle flow by returning a `Response`:
370
- * If a before filter returns it, both the action and the after filters will be skipped (as well as any remaining filters in the before list)
371
- * If an after filter returns it, any remaining after filters in the block will be skipped.
372
- * There is no way for the action result to skip the :after filters.
373
- * Refactored Controller module to properly used ActiveSupprt concerns. [@jasonayre](https://github.com/jasonayre) [Issue #26](https://github.com/rightscale/praxis/issues/26)
374
- * Separated the controller module into a Controller concern and a separable Callbacks concern
375
- * Controller filters (i.e. callbacks) can shortcut request lifecycle by returning a Response object:
376
- * If a before filter returns it, both the action and the after filters will be skipped (as well as any remaining before filters)
377
- * If an after filter returns it, any remaining after filters in the block will be skipped.
378
- * There is no way for the action result to skip the :after filters.
379
- * Fixes [Issue #21](https://github.com/rightscale/praxis/issues/21)
380
- * Introduced `around` filters using blocks:
381
- * Around filters can be set wrapping any of the request stages (load, validate, action...) and might apply to only certain actions (i.e. exactly the same as the before/after filters)
382
- * Therefore they supports the same attributes as `before` and `after` filters. The only difference is that an around filter block will get an extra parameter with the block to call to continue the chain.
383
- * See the [Instances](https://github.com/rightscale/praxis/blob/master/spec/spec_app/app/controllers/instances.rb) controller for examples.
384
- * Fix: Change :created response template to take an optiona ‘location’ parameter (instead of a media_type one, since it doesn’t make sense for a 201 type response) [Issue #26](https://github.com/rightscale/praxis/issues/23)
385
- * Make the system be more robust in error reporting when controllers do not return a String or a Response
386
- * Fix: ValidationError not setting a Content-Type header. [Issue #39](https://github.com/rightscale/praxis/issues/19)
387
- * Relaxed ActiveSupport version dependency (from 4 to >=3 )
388
- * Fix: InternalServerError not setting a Content-Type header. [Issue #42](https://github.com/rightscale/praxis/issues/42)
389
- * A few document browser improvements:
390
- * Avoid showing certain internal type options (i.e. reference).
391
- * Fixed type label cide to detect collections better, and differentiate between Attributor ones and MediaType ones.
392
- * Tweaked _example.html template to be much more collapsed by default, as it is not great, but makes it easier to review.
393
- * Enhanced _links.html template to use the rs-type-label, and rs-attribute-description directives.
394
- * Small design improvements on the home page for showing routes and verbs more prominently.
395
- * Mediatype documentation improvements:
396
- * Make `Links` always list its attributes when describe (never shallow)
397
- * refactored MediaTypeCollection to store a member_attribute (instead of a member_type), and report it in describe much like attributor collections do.
398
- * `MediaTypeCollection`. See [volume_snapshot](spec/spec_app/design/media_types/volume_snapshot.rb) in the specs for an example.
399
- * Added `member_view` DSL to define a view that renders the collection's members with the given view.
400
- * Change: Now requires all views to be explicitly defined (and will not automatically use the underlying member view if it exists). To define a view for member element (wrapping it in a collection) one can use the new member_view.
401
- *
402
-
399
+ - Avoid loading responses (and templates) lazily as they need to be registered in time
400
+ - Fix: app generator's handling of 404. [@magneland](https://github.com/magneland) [Issue #10](https://github.com/rightscale/praxis/issues/10)
401
+ - Fix: Getting started doc. [@WilliamSnyders](https://github.com/WilliamSnyders) [Issue #19](https://github.com/rightscale/praxis/issues/19)
402
+ - Controller filters can now shortcut the request lifecycle flow by returning a `Response`:
403
+ - If a before filter returns it, both the action and the after filters will be skipped (as well as any remaining filters in the before list)
404
+ - If an after filter returns it, any remaining after filters in the block will be skipped.
405
+ - There is no way for the action result to skip the :after filters.
406
+ - Refactored Controller module to properly used ActiveSupprt concerns. [@jasonayre](https://github.com/jasonayre) [Issue #26](https://github.com/rightscale/praxis/issues/26)
407
+ - Separated the controller module into a Controller concern and a separable Callbacks concern
408
+ - Controller filters (i.e. callbacks) can shortcut request lifecycle by returning a Response object:
409
+ - If a before filter returns it, both the action and the after filters will be skipped (as well as any remaining before filters)
410
+ - If an after filter returns it, any remaining after filters in the block will be skipped.
411
+ - There is no way for the action result to skip the :after filters.
412
+ - Fixes [Issue #21](https://github.com/rightscale/praxis/issues/21)
413
+ - Introduced `around` filters using blocks: \* Around filters can be set wrapping any of the request stages (load, validate, action...) and might apply to only certain actions (i.e. exactly the same as the before/after filters)
414
+ - Therefore they supports the same attributes as `before` and `after` filters. The only difference is that an around filter block will get an extra parameter with the block to call to continue the chain. \* See the [Instances](https://github.com/rightscale/praxis/blob/master/spec/spec_app/app/controllers/instances.rb) controller for examples.
415
+ - Fix: Change :created response template to take an optiona ‘location’ parameter (instead of a media_type one, since it doesn’t make sense for a 201 type response) [Issue #26](https://github.com/rightscale/praxis/issues/23)
416
+ - Make the system be more robust in error reporting when controllers do not return a String or a Response
417
+ - Fix: ValidationError not setting a Content-Type header. [Issue #39](https://github.com/rightscale/praxis/issues/19)
418
+ - Relaxed ActiveSupport version dependency (from 4 to >=3 )
419
+ - Fix: InternalServerError not setting a Content-Type header. [Issue #42](https://github.com/rightscale/praxis/issues/42)
420
+ - A few document browser improvements:
421
+ _ Avoid showing certain internal type options (i.e. reference).
422
+ _ Fixed type label cide to detect collections better, and differentiate between Attributor ones and MediaType ones.
423
+ _ Tweaked \_example.html template to be much more collapsed by default, as it is not great, but makes it easier to review.
424
+ _ Enhanced \_links.html template to use the rs-type-label, and rs-attribute-description directives. \* Small design improvements on the home page for showing routes and verbs more prominently.
425
+ - Mediatype documentation improvements:
426
+ _ Make `Links` always list its attributes when describe (never shallow)
427
+ _ refactored MediaTypeCollection to store a member_attribute (instead of a member_type), and report it in describe much like attributor collections do.
428
+ - `MediaTypeCollection`. See [volume_snapshot](spec/spec_app/design/media_types/volume_snapshot.rb) in the specs for an example.
429
+ - Added `member_view` DSL to define a view that renders the collection's members with the given view.
430
+ - Change: Now requires all views to be explicitly defined (and will not automatically use the underlying member view if it exists). To define a view for member element (wrapping it in a collection) one can use the new member_view.
431
+ -
403
432
 
404
433
  ## 0.9 Initial release