group resources by path

[woylie]

Addresses issue #2.

[coveralls]

Coverage increased (+0.1%) to 94.382% when pulling 24cbffd on group-by-path into af71c6d on master.

[woylie]

This fixes the aglio warnings. Aglio will now group the resources in the navigation bar like this:

I preferred it the way before, but I don't like the warnings.

Aglio will only show route parameters if they are defined within our macro. In the next screenshot, both actions are grouped under the same resource path /cats/{id}, but the id is only displayed in the first action.

[woylie]

It turns out that it is possible to define parameters directly under the resource path headers. For example:

## /cats/{id}

+ Parameters

    + id

### DELETE

You can put all parameters under the resource path headers as above, or you could place the route parameters under the resource path headers and the query parameters under the action headers, like this:

## /cats/{id}{?delivery-method}

+ Parameters

    + id

### DELETE

    + Response 204

### GET

    Parameters

        + delivery-method

    + Response 200

The generated action headers and example routes will then always contain the path parameters (as they should), but only include those query parameters that are included in the tests.

This would be very nice for the generated documentation, but we would have to determine how to get the parameter information of all the actions on a path. We'd have to define the resource path information separately from the api/3 macro.

[rhazdon]

Yes, this will be a challenge. But I think this will not be that difficult. We have to expand the logic for matching the documented routes with the "real" routes a little bit, like cutting the routes for parameter or allowing them.

[woylie]

I don't know what you mean with cutting the routes for parameter or allowing them. We don't have to do anything special with routes. The question is this: We define the parameters at the action level, but now we want to display some of them one step higher in the hierarchy. If we leave the macros as they are, we would have to pick one of actions within a resource section and use the parameter information used there. But we don't want to do that. So we would have to define the route parameters within a third macro just for the resource section. But I don't like that either for usability reasons.

Let's leave this pull request as it is for now and release 0.3.1 soon.

[coveralls]

Coverage increased (+0.1%) to 94.382% when pulling 9e21ad5 on group-by-path into 4129768 on master.

[coveralls]

Coverage increased (+0.1%) to 94.382% when pulling 03bc904 on group-by-path into 4129768 on master.