mill
mill copied to clipboard
Deprecate parameter tokens for a new trait system.
With the new MSON work being done in mill#42, the current parameter token system is no longer viable.
The way it was originally constructed was that it would str_replace
content from the token, "{string} direction (optional) The direction that the results are sorted." onto the @api-param
annotation: "@api-param:private {direction} [asc|default|desc] Sort direction". This has resulted in funky API Blueprint content being generated:
- `direction` (enum[string]) - The direction that the results are sorted. Sort direction
+ Members
+ `asc`
+ `default`
+ `desc`
With he move to MSON for parameters and representations, this format will no longer be viable because of the wide difference between MSON content and how a string replace would work.
So the solution to fix this is to construct a new "trait" system.
The basic idea is that we'd replace the parameterTokens
config with traits
. You would load traits with a @api-trait
annotation, and then specify additional data to override that trait with, like a description, or new enum values.
- [ ] Replace the
<parameterTokens>
config XML declaration with a<traits>
config. - [ ] Traits will be configured as MSON within
<trait>
blocks:
<trait name="filter_playable">
`true` (string, default, optional) - Choose between only videos that are playable, and only videos that are not playable.
+ Members
- `true`
- `false`
</trait>
- [ ] You will load traits within a resources as:
@api-trait filter_playable
- [ ] Traits should support overloading data by just adding that data onto the
@api-trait
annotation:
@api-trait filter_playable - This is an overloaded description
+ Default: `yes`
+ Members
- `yes`
- `no`
- [ ] Traits should be able to be versioned.
- [ ] For response data that is only present when a trait on that resource is present, you should be able to specify this in your representation data declaration with a
@api-traitEnabled trait_name
annotation.- The use-case for this might be something like response pagination where one resource is paginated, but another isn't, despite them returning the same representation.
- [ ] In compiled API Blueprint files, traits should look as regular parameters and representation data (because essentially they are).
- [ ] Traits should support visibilities.
For some additional background, see: