DateTime examples in yaml show validation error in https://studio.asyncapi.com/ (issue raised in AsyncAPI Studio)

[pdalfarr]

Describe the bug
Using the https://www.springwolf.dev/docs/configuration/#actuator-support feature, I downloaded the docs.yaml from my back-end using url http://localhost:8450/actuator/springwolf/docs.yaml
Then I used this docs.yaml in both https://studio.asyncapi.com/ and https://editor.swagger.io/ but validation errors occurs

Dependencies and versions used
springwolf-core and springwolf-amqp 0.17.0

Code example
No code example as I cannot disclose my asyncapi definition.
One can use its own docs.yaml and follow the procedure describe above to reproduce this 'bug'

Stack trace and error logs
No stacktrace, as the problem is not an exception, but rather, a possible issue in the generated docs.yaml

Question
I noticed that asyncapi version in generated docs.yaml is 2.6.0. Maybe it would be better if it was 3.0.0 ?
How can I make Springwolf generate a 3.0.0 asyncapi docs.yaml file?

[timonback]

Hi @pdalfarr
Thank you for the report.

We are actively building on AsyncApi 3.0, which will resolve this.

AsyncApi 3.0 includes bigger changes, requiring also a significant time investments on our side to adapt Springwolf.
Subscribe to #494 and #507 to get updates.

[timonback]

Thank you for the report, the issue has been addressed in the new release.

Feel free to reopen this issue if there is still something missing.

[pdalfarr]

Hi,

I tested the generated asyncapi 3.0.0 generate yaml and it is pretty much OK, except for a few things I had to fix by hand.
( https://studio.asyncapi.com/ helped me to understand the errors thanks to the lower pane with messages warnings and errors ;-) )

I can not disclose neither the source code, nor the generated asyncapi file , but I can share the fix I made by hand:

1. add a missing "host" element in servers.amqp
   servers.amqp.host: localhost:5672

2. payload examples with date attribute: add missing double quotes:
   components.schemas...MyMessage.examples[0].activites[0].periodeDate.debut: 2015-07-20
   -> components.schemas....MyMessage.examples[0].activites[0].periodeDate.debut: "2015-07-20"

same goes for createdOn: 2015-07-20T15:49:04-07:00 -> createdOn: "2015-07-20T15:49:04-07:00"

3. enum example payload are surrounded with '"..."' : single quote, then double quotes, then enum string value, then double quote and finally single quote.
   I had to remove these.
   components.schemas....MyMessage.examples[0].typeReference: '"ENUM_VALUE"'
   -> components.schemas....MyMessage.examples[0].typeReference: ENUM_VALUE

4. formatting problem for some entries in components.schemas
   (where does the leading '?' come from.. I have no clue , also the trailing ":" is on the next line..)

    ? my.package.MyMessage
    : type: object

so I fixed these like so:

    my.package.MyMessage:
      type: object

also occurring under operation:

operations:
  ? my-receiveCommunicationReply
  : action: receive

and I fixed it like so:

operations:
  my-receiveCommunicationReply:
    action: receive

5. "schemaFormat" and "schema" in messages. I had to remove these lines, and 'move up one level the $ref element

not working:

  messages:
    My.MessageEvent:
      payload:
        schemaFormat: application/vnd.aai.asyncapi+json;version=3.0.0
        schema:
          $ref: '#/components/schemas/My.MessageEvent'

I had to change it like so:

  messages:
    My.MessageEvent:
      payload:
        $ref: '#/components/schemas/My.MessageEvent'

Still, the asyncapi 3.0.0 it's a great step forward, and I really want to thank you (and all contributors) for this.

I hope my feedback is sufficient for you to investigate.

Regards,

Pascal

[pdalfarr]

Additional note about "schemaFormat" and "schema" issue:

https://studio.asyncapi.com/ does NOT report the presence of these 2 elements as being an issue, BUT the IntelliJ AsyncAPI plugin https://plugins.jetbrains.com/plugin/15673-asyncapi does.

[timonback]

Thanks for the update. I updated the release notes -> migration guide to explicitly mention the host and protocol field.

---

I took a quick look at the springwolf-examples/springwolf-kafka-example to generate a yaml document.
It generates the document at https://pastebin.com/k4JVsChx, which is valid according to AsyncApi Studio.

There:
2. Dates do have quotes (I had to modify the example, not included in the pastebin)
3. Enum do only have 1 pair of double quotes
4. Not sure where the ? and : is coming from
5. As you mention as well, it is fine in AsyncApi Studio. I checked the same kafka example using the Intellij Plugin. It displays errors on some messages, however not on all. This is surprising to me, as they all do have the same structure. -> Is this an issue in the Intellij plugin?

---

Can you adapt one of the springwolf examples (for example kafka) so that we can reproduce the issues there?
Is probably sufficient to update one of the DTO objects https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples/springwolf-kafka-example/src/main/java/io/github/springwolf/examples/kafka/dtos/ExamplePayloadDto.java

You can test the yaml output locally by running the ApiIntegrationTest (requires docker). Just change the url in

springwolf-core/springwolf-examples/springwolf-kafka-example/src/test/java/io/github/springwolf/examples/kafka/ApiIntegrationTest.java

Line 35 in a3b4743

String url = "/springwolf/docs";

to String url = "/springwolf/docs.yaml";

[pdalfarr]

Hi,

I am using Rabbit, not Kafka.
Which Rabbit example can I use?

In the mean time, I'll try to debug on my side.

[timonback]

Hi @pdalfarr,
check out the springwolf-amqp example project right next to the kafka example at
https://github.com/springwolf/springwolf-core/blob/a3b4743b825efa79added6d186ea4e581dce0f2b/springwolf-examples/springwolf-amqp-example/src/main/java/io/github/springwolf/examples/amqp/dtos/ExamplePayloadDto.java

[pdalfarr]

Hi

Debugging com.fasterxml.jackson.core.io.SegmentedStringWriter gave a first insight:

One of my Rabbit messages classes is a generic:

public class ContexteMessage<T> {

    @Valid
    public T contexte;
}

and it seems yamlMapper has an hard time serializing this

cfr

springwolf-core/springwolf-asyncapi/src/main/java/io/github/springwolf/asyncapi/v3/jackson/DefaultAsyncApiSerializerService.java

Line 31 in a8f18eb

return yamlMapper.writer(printer).writeValueAsString(object);

Which eventually leads to

https://github.com/snakeyaml/snakeyaml/blob/master/src/main/java/org/yaml/snakeyaml/emitter/Emitter.java#L620

hence the "?" in the generated yaml

I keep digging.

[timonback]

Hi @pdalfarr, any update on what you have discovered?