Request parameters breaking when examples and copy has underscores

[earnaway]

I've noticed an issue when there are underscores as part of the params in the resources.

Here's an example:

## Resource Title [/resource/{id}/info{?status,order_by,sort,page,per_page}]

+ Parameters
    + id: 64 (required, string) - user id  or 'me'
    + status: paid (optional, string) - transaction status, one of pending, validated, paid, denied
    + order_by: transaction_date (optional, enum) - one of transaction_date, some_name, amount, user_status, status
    + sort: asc (optional, enum) - one of asc, desc
    + page: 1 (optional, integer) - pagination parameter
    + per_page: 5 (optional, integer) - pagination parameter

When running aglio against the above, I get the error:

>> Line 867: parameter 'order_by: transaction_date' not specified in 'Resource Title' its '/resource/{id}/info{?status,order_by,sort,page,per_page}' URI template (warning code 8)

But if I remove all the underscores from the "order_by" params and replace it with:

+ order_by: transactiondate (optional, enum) - one of transactiondate, somename, amount, userstatus, status

Then it works! I think the parser is breaking on underscores as parameters.

Anyone else come across this before?

[danielgtaylor]

@earnaway interesting, this looks like an upstream bug in the parser. I'll try to investigate and see if it's still happening with the latest major release (which Aglio will be moving to in the near future).

[earnaway]

Thanks. Any idea how soon you might be moving the next major release?

[danielgtaylor]

@earnaway the major breaking work on the C++ parser is done now with the release of Drafter 1.0.0 and Protagonist 1.0.0, however there are still some missing features and some bugs that won't break backward compatibility. Those are being worked on now, and the plan is to use an upcoming release of Fury in Aglio soon. It's at least a few weeks away, but it's going to come with some neat new possibilities like better support for MSON.

[ghost]

can confirm, it's definitely breaking with underscores in the description.

This breaks:

+ Parameters
  + grant_type: `23123` (string, required) - The type of authentication, should be refresh_token

It appears as:

[earnaway]

Anyone managed to find a workaround or get this fixed for underscores in the description?

[juno]

Hi @earnaway , I had same problem with aglio and found a solution at https://github.com/apiaryio/api-blueprint/issues/224 .

If you read the MSON spec, you can see that _ is a reserved character. Please use backticks to escape the whole word. Here is an example:

+ `some_thing`: `an_example_thing`

This solved my problem, I hope this helps you.

[ghost]

That makes sense, would be cool to include examples of that in the docs 👍

[earnaway]

Thanks @juno, works perfectly now with a recent update!