conditionalFiles only works if you are lucky

[Tenischev]

Describe the bug

1. Description of conditionalFiles in docs is incomplete and example is actually pitfall.
2. If subject is not resolved in AsyncAPI, then file will be rendered because of this condition

How to Reproduce

Just try to use provided example

Expected behavior

1. Add note that path of file should be relative to tempalte folder
2. If subject is not found in AsyncAPI, then file is not rendered
3. Add note that validation is not any JSON Schema Draft 07 object, it must be from JSON Schema Validation
4. Provide a valid example:
   Correct subject path in term of AsyncAPI spec to server protocols will be servers.*.protocol, but result of this (and any other) resolution will be an array, you should take it into account. Since it's not possible to predict how much servers will be in user AsyncAPI, usage of const is not possible as is. Perhaps, contains should be used always to check against result array.
   Here an example of validation that will correctly check for the mqtt protocol { "contains": { "type": "string", "const": "mqtt" }}.
   Or another approach where filtering delegated to subject - "subject": "servers.*.{protocol: protocol} | [?protocol=='mqtt']", "validation": { "const": [ { "protocol": "mqtt" } ] }

Hint

Perhaps we have a bug in nodejs template because it's exact copy of example from cuurent doc

[derberg]

One thing sure here is that current conditionalFiles in nodejs-template do not make sense as files listed there do not exist in the tempalate anyway https://github.com/asyncapi/nodejs-template/blob/master/package.json#L88

[derberg]

After some investigation:

• current configuration of conditionalFiles from nodejs-template can be removed https://github.com/asyncapi/nodejs-template/blob/master/package.json#L88 as files like amqp.js or mqtt.js do not exist in the template anymore
• I think the feature and the example work pretty well, just tested it in nodejs-template and it worked like a charm (my spec files has 3 servers). I added this:

"conditionalFiles": {
      "config/common.yml": {
        "subject": "server.protocol",
        "validation": {
          "const": "amqp"
        }
      }
    }

and if I generate service using my mqtt server, the file is not generated -> this is what I expected

I'm more concerned about:

• nonRenderableFiles are not supported by conditionalFiles, and I think they should
• I don't get what is the point of nonRenderableFiles as current use case in nodejs-template doesn't make sense to me https://github.com/asyncapi/nodejs-template/blob/master/package.json#L80 as if I remove those files from nonRenderableFiles then are generated just fine

[derberg]

@Tenischev server.protocol works because this is apparently not a documented feature :)
https://github.com/asyncapi/generator/blob/master/lib/generator.js#L561

[derberg]

@Tenischev I tried to replace your hook by configuration in java-template but you do not support server parameter there. If users have 2 servers, how do you guess which one they should use for generation?

[derberg]

We could also have a nice warning for template developers in template config validation so they know they have wrong conditions, for files that do not exist. That would be a separate feature issue though

[derberg]

@Tenischev I created a PR for java, have a look and tell me what you think https://github.com/asyncapi/java-spring-template/pull/55/files

[derberg]

@Tenischev I created PR for docs in generator #363

@fmvilas have a look on my comment

nonRenderableFiles are not supported by conditionalFiles, and I think they should
If you agree I will extend this PR with proper fix

[fmvilas]

Yeah, I think it totally should 👍

[derberg]

@fmvilas PR ready for review

@Tenischev
there are 2 PR related to this issue you might want to look at:

• feat: support files listed in nonRenderableFiles with conditionalFiles #363
• feat: add server param ands support for conditions java-spring-template#55

[Tenischev]

Hey @derberg ,
Now i see on asyncapi/java-spring-template#55 and want to say "Oh, this is what was mean here in description"
We should expose description of server parameter to describe that you should name one of the servers listed in "servers" of your AsyncAPI
Nevertheless, parameter is very confusing for me, i should think

[derberg]

@Tenischev well, the current description of the server is accurate, it just doesn't say anything about conditionalFiles.

I've extended my PR with more explanation, examples and links. What do you think?

[asyncapi-bot]

🎉 This issue has been resolved in version 0.52.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀