apiaryio/snowcrash

Default parameter value is not always parsed

Closed this issue · 4 comments

zdne commented

API Blueprint example blueprint does not parse correctly – 09. Advanced Attributes.md

Parsing following will result in error: warning: (5) ignoring unrecognized block :55:16 (the default value is not parsed:

# R [/r/{id}]
+ Parameters
    + id (optional)
        + Default: `20`

Following parses OK:

# R [/r/{id}]
+ Parameters
    + id: 0 (optional)
        + Default: `20`

See the specification: URI parameters section

@zdne That is correct. In the first instance, parser assumes that the parameter style is the old style and doesn't recognise the Default. In the second instance, parser sees the : and parses it using MSON style.

This is because, we default to old style parsing when we don't have any special characters like = or : in parameter signature.

Though, I understand that we can lookahead and see the Default keyword, but that is going to be a bit tricky with our architecture.

zdne commented

@pksunkara the main problem with this the incorrect example in API Blueprint repo.

zdne commented

Well we at the very least need to issue a better warning – this is super confusing – and conforming the spec => really poor user experience .

When there is a list item within the property we could perhaps assume it's the new style instead? So once + Default is present, it's treated as an MSON style parameter.