Support server URL variables

[fmvilas]

Currently, the generator doesn't support server URL variables. For instance, when we have a server like this:

servers:
  production:
    url: test.mosquitto.org:{port}
    protocol: mqtt
    description: Test broker
    variables:
      port:
        description: Secure connection (TLS) is available through port 8883.
        default: '1883'
        enum:
          - '1883'
          - '8883'

The generated code tries to connect to mqtt://test.mosquitto.org:{port}. It would be great if it could replace port by a generated value, i.e., the default value or a valid one, based on the variable definition.

[derberg]

@fmvilas hey, can you share some more explanation here, I'm not fully getting what can be done here. My first attempt would be to replace {port} with default, but then looking at https://www.asyncapi.com/docs/specifications/2.0.0/#a-name-servervariableobject-a-server-variable-object I learn default is not required, so I would say, fallback to default is the first item from enum list. It could also be parametrized, and the user could maybe do -p variable.port.default.

Or...maybe this url: test.mosquitto.org:{port} should be explicit? and say url: test.mosquitto.org:{port.default}?

[fmvilas]

I think it should go this way:

1. Check if there's a default value: if so, use it. Otherwise, continue to 2.
2. Check if there's an enum. If so, get the first one. Otherwise, continue to 3.
3. Do nothing, as it is right now. Maybe log a warning message would be great, but anything else.

say url: test.mosquitto.org:{port.default}?

{port.default} is a variable itself. Different from {port}. I'd not introduce syntax/expressions on the variable names just because it would be great to have them on the generator. Let's be cautious with making the spec a config file for our tools.

What do you think?

[derberg]

I actually did not take into account that port.default could be an individual variable. You're right.

So default -> 1st enum -> warning

2 more questions:

• what templates are we talking here about? all? only the code related ones, right? for docs you do not want such magic
• is parser already warning the user that he has a variable (in url like in example) that is not defined under variable parameter?

I'm also thinking where later describe such functionality, so the user knows how it works without reading the templating. Or maybe it is enough to log clearly, that in case of default, log will say default was used, in case of enum, log will say first enum was used?

[fmvilas]

what templates are we talking here about? all? only the code related ones, right? for docs you do not want such magic

Correct. That's only for code generation templates. So far, I'd only target the Node.js template.

is parser already warning the user that he has a variable (in url like in example) that is not defined under variable parameter?

Nope, no warnings yet. This would be a great use case for stoplightio/spectral#965. Actually, I'd forget about triggering warnings in the generator for now. Just go for: default -> 1st enum -> nothing (like now).

If we're going to log warnings we should probably make them customizable, and that's a Spectral ruleset in the end.