UriTemplate not evaluated correctly

[it-ony]

According to the specification https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#form-style-query-variable an uri-template like /foo/bar{?a,b} should result in an uri /foo/bar?a=foo&b=bar if the parameters are set to a=foo and b=bar.

Right now the result looks /foo/bar{?a,b}.

[danielgtaylor]

@it-ony the rendered documentation will show the URI template, not its evaluated result. Where are you expecting the evaluated result to be shown?

[it-ony]

@danielgtaylor I was expecting to show it where right now the template is shown, but in an evaluated format.

/foo/bar{?a,b} should just transformed to /foo/bar?a=fo0&b=bar. The values should be taken from the configured parameters, with their default values.

I tried the same api blueprint code at apiary.io and the display it in an evaluated format.

[pksunkara]

In Apiary, the evaluated result will be shown in the console only since parameters are specific to console. The non-evaluated is the one which will be shown in the documentation.

[it-ony]

Ok, what do you think about showing the defaults and also formatting the url? Query parameters shwosn as {?a,b} is not common for users reading the documentation. Using an uri template like /foo/bar?a={a}&b={b} will help out to show the uri in the documentation correctly, but seems wrong to me according to the specification.

[danielgtaylor]

@it-ony I like the idea of showing a generated example, but I worry about showing incorrect information. For example:

# My Resource [/frobs{?foo,bar}]
## Get a Frob [GET]
+ Parameters
  + foo: `fooString` - Passes a foo value. Mutually exclusive with `bar`!
  + bar: `barString` - Passes a bar value. Mutually exclusive with `foo`!

Now, you would generate /frobs?foo=fooString&bar=barString or something like that, which is absolutely wrong and will cause confusion.

[it-ony]

@danielgtaylor Is there a way to define dependencies with the apiblueprint's? As I guess the answer is no, I think the uri just gives you a hint of how to use it. If there are special rules, e.g. parameters cannot be used together such an uri, will help you more then a uri of the scheme /frobs{?foo,bar}.

As this is a GET request, I also ask myself, if there is any valid use-case for mutually exclusive parameter, or if just one parameter should win, if both are specified.

[danielgtaylor]

@it-ony I've been working on an implementation of this idea. I don't think the mutually exclusive options should be a blocker for now since this has the potential to help a lot of people with little or no URI template experience. Example of what I'm working on for the next release:

What do you think?

[it-ony]

Pretty cool!

@it-ony I've been working on an implementation of this idea. I don't think the mutually exclusive options should be a blocker for now since this has the potential to help a lot of people with little or no URI template experience. Example of what I'm working on for the next release:

What do you think?

— Reply to this email directly or view it on GitHub.

[danielgtaylor]

This is now released in olio-theme-1.3.0. Please let me know if you find any problems with it!