search

erunion / mill

☴ An annotation-based DSL for documenting a REST API.
MIT License
39 stars 2 forks source link

Parameter tokens with overridden descriptions end up weird. #58

Closed erunion closed 7 years ago

erunion commented 7 years ago 
<parameterTokens>
    <token name="direction">{string} direction (optional) The direction that the results are sorted.</token>
</parameterTokens>
@api-param:private {direction} [asc|default|desc] Sort direction

Is compiled into API Blueprint as:

- `direction` (enum[string]) - The direction that the results are sorted. Sort direction
    + Members
        + `asc`
        + `default`
        + `desc`

The problem with fixing this is that right now we're doing a straight string replace for the token, and that doesn't care about the existing data.

I don't exactly know how to fix this other than running a quick parse of the existing parameter (pre-token replacement) to parse out its data, then drop the token in, re-parse and replace the tokens' data with the previously parsed content.

This is also going to be problematic with the coming MOSN work (#42), but that's going to most likely require revisiting the entire concept of parameter tokens.

erunion commented 7 years ago

This is being addressed in #62 with a new traits system.