Grouping of endpoints

[grabbou]

Hey, After updating, my endpoints are no longer grouped... They all appear under 'api' tag, instead of being grouped by the first part of the endpoint url, e.g. "auth", "users", "pets". Any ideas?

[grabbou]

For now, only grouping by tag works, but unfortunately, routes are duplicated as there needs to be at least one common tag for all of them (e.g. "api"). In that case, descriptions do not work.

I would also suggest updating readme file as providing multiple tags for requiredTags requires all of them to be present in a route in order to be displayed. The current version suggest that one of the required tags should be present.

[grabbou]

Version 1.3.0 does not group by tags (looks like they are ignored) which is what I was looking for. It also supports descriptions. In that version the weird behaviour of requiredTags is also gone (works like stated in readme)

[z0mt3c]

Right! Its due to a change in swagger-ui. Before 2.1 tags were ignored an the first segment of the path was used. Now all routes will be listed beneath all of their tags (i always passed the hapi tags through) which actually gives us much more flexibility because we can change what its grouped by. (e.g. grouping after the first & second path)

This change was not introduced by hapi-swaggered actually it came with the version increase of swagger-ui in hapi-swaggered-ui@1.3.0. So staying with 1.2.x should work for now (if you are on hapi-swaggered@1.x). With hapi-swaggered-ui@1.3.x (through swagger-ui@2.1.x) the support of the swagger specs 2.0 were introduced. (Support of the 2.0 specs is coming with hapi-swaggered@2.0 which is currently in alpha stage).

I'm planning to introduce some new configurations regarding the grouping with 2.0 (and i might backport it). What do you think which options are worth considering it?

• grouping by tags (but removing the api one?)
• grouping by nth path level (default: only the first level - to restore previous behavior)

Which version of hapi-swaggered are you using?

[grabbou]

For now, I've jumped back to 1.3.0 for the backend and ^1.2.3 for the frontend side.

I am happy to have grouping by tags, but then, we need to consider the following things:

• the requiredTags should work as stated in readme - if I specify [api, swagger] - it means I expect either api or swagger routes to appear, not the ones that have both of those tags specified
• the requiredTags tags should be skipped when grouping if a route contains more tags than the required ones. So if a route has api, auth it should appear under auth. Not under both api and auth as currently. But if it contains only api tag, it should appear under api section as a kind of global route.

Actually, we can leave the grouping by path by default and expose groupByTags parameter (then, hapi-swaggered-ui will look for tags description in the same place where it looks for path descriptions).

Currently, in my case, where all my routes are prefixed with /project/{id}/ (multiple projects in a SaaS based architecture), I am a huge fan of grouping by tags as it's more flexible in that case.

[z0mt3c]

Published a v2.0.0-alpha.9

New configuration:

• tagging: Options used for grouping routes
  • mode: string, can be path (routes will be grouped by its path) or tags (routes will be grouped by its tags), default is path
  • pathLevel integer, in case of mode path it defines on which level the path grouping will take place (default is 1)
  • stripRequiredTags boolean, in case of mode tags it defines if the requiredTags will not be exposed (default is true)

Still have to write some additional tests (also covering the description stuff) but have a look and tell me what you think.

[grabbou]

Yeah, the pathLevel looks really promising to me! Will update later today and let you know :)

[z0mt3c]

I will close the issue - but still waiting for ur feedback ;-)

[grabbou]

Works perfectly, still wondering if we should strip leading / when grouping by path? E.g. I would expect my endpoints to be grouped under auth instead of /auth.

[z0mt3c]

foo and with pathLevel: 2 foo/bar or stick with /foo and /foo/bar

[grabbou]

Ok, I am gonna leave it as is for now. Don't want to prepend my routes with anything unnecessary as staying 100% rest-compatible is what I require at this point

[z0mt3c]

done and released