Allow '/' in URI parameters - support level 2 URI templates

[nohorbee]

The spec says:

The baseUri property's value MUST conform to the URI specification [RFC2396] or a Level 1 Template URI as defined in RFC 6570 [RFC6570].

In order to be able to document more versatile APIs, Level 2 templates should also be allowed, but only if the macro is the last piece in the URL

Example:

#%RAML 0.8
title: My Sample API
/files{+path}:
  uriParameters:
    path:
      description: The full path to the desired file
      type: string
      example: /my/file

[dmartinezg]

Hi @usarid, I think that we should not tentatively reject this one, it is super important for writing meta-apis.

This means that we need to do a ton of workarounds to get this working on Osprey, or anything else. Can we review the status?

[usarid]

A quote from the URI template RFC is in order:

Some URI Templates can be used in reverse for the purpose of variable matching: comparing the template to a fully formed URI in order to extract the variable parts from that URI and assign them to the named variables. Variable matching only works well if the template expressions are delimited by the beginning or end of the URI or by characters that cannot be part of the expansion, such as reserved characters surrounding a simple string expression. In general, regular expression languages are better suited for variable matching.

So while we could have a better chance of ending up with template URIs that work for variable matching by allowing level 2 only at the end of the URI, there's no guarantee, and we'd be losing some valid possibilities from the level 2 spec.

Instead, let's go for full support of level 2, and if a URI template ends up with ambiguities -- it could be valid RAML but a non-workable API spec. We already have such cases, such as URI paths that differ only by constraints on URI parameter values (/users/me and /users/{userId}`) and those constraints may not be provably unambiguous. We will leave it up to users and tool makers to help avoid such ambiguities, rather than making the ambiguities impossible to encounter in the first place.