Easier control over quotes / always quote string values in YAML?

ccudennec-otto commented 3 months ago

Describe the feature request I'm trying to render my asyncapi.yaml in https://studio.asyncapi.com/ but that tool seems to have problems if the values in the YAML are not quoted. As an example: I have an object that defines a date field and defines the example as appointmentDate: 2015-07-20. In that case AsyncAPI studio shows me an error. If I quote the value using double quotes it does not show an error.

I was able to solve the issue by implementing my own AsyncApiSerializerService and defining it as a bean. My implementation will additionally disable the feature Feature.MINIMIZE_QUOTES for YAML.

Motivation I think this is rather an issue of AsyncAPI studio, because the unquoted value is fine according to the JSON schema specification.

But it would be nice to instantly see the result in AsyncAPI studio anyway. Giving easier control over the way the output is rendered would be a good feature anyway IMHO.

Technical details

What do you think about turning your ObjectMapper instances into optional beans with specific names? This would simplify the configuration for consumers.
What do you think about changing the default in SpringWolf and always quote string values?

Describe alternatives you've considered As explained above, my current solution defines my own implementation of AsyncApiSerializerService with customized behaviour.

I'm happy to get your thoughts and feedback.

Cheers,

Christopher

sam0r040 commented 3 months ago

Hi @ccudennec-otto, thanks a lot for your feedback. It helped us to build a solution for this release in https://github.com/springwolf/springwolf-core/pull/822. Feature.MINIMIZE_QUOTES is now always configured for YAML Examples when using the compatibility mode for AsyncApi Studio (which is ON by default).

Exposing the ObjectMappers sounds like a good idea. Springwolf currently uses multiple ObjectMappers for serialization:

You are welcome to allow ObjectMapper customization as a contribution.

ccudennec-otto commented 2 months ago

Hi @sam0r040!

I've just tried Spring Wolf 1.5.0 but for me it does not generate different output. The reason is that your code changes did not change the implementation of DefaultAsyncApiSerializerService in #822 or did I miss something? As you've mentioned yourself, all classes that create their own (YAML) ObjectMapper would need to disable the feature.

I can contribute the code changes if you agree that this is missing. 😃

Cheers,

Christopher

timonback commented 2 months ago

Hi @ccudennec-otto, we understood the problem to be located in the example generation, which has also an ObjectMapper. So we fixed that in https://github.com/springwolf/springwolf-core/pull/822 there and added the studio compatiblity mode.

Actually, you can configure the objectMapper of the DefaultAsyncApiSerializerService by calling getYamlObjectMapper and enabling/disabling features.

Of course you are welcome to contribute a code change.

As a side note, lately we have been seeing activity in studio to address the issue there as well: https://github.com/asyncapi/studio/pull/1124

ccudennec-otto commented 2 months ago

I don't know when the code for the example generation is actually used. I generate the AsyncAPI documentation by GETting the YAML response from the AsyncApiController. The AsyncApiSerializerService does not seem to use your changed code.

I try to prepare a PR to illustrate the changes.

As a side note, lately we have been seeing activity in studio to address the issue there as well: https://github.com/asyncapi/studio/pull/1124

Getting the fix in AsyncAPI studio would be even better. 😃

I've also raised an issue on their side to fix the issue a while ago: https://github.com/asyncapi/studio/issues/1119

aeworxet commented 2 months ago

Validation of type date was fixed in both studio and studio-next.

timonback commented 2 months ago

Hello, welcome and thank you @aeworxet

I just merged https://github.com/springwolf/springwolf-core/pull/881 so that we got the updated parser-js now.

@ccudennec-otto You can try the snapshot version, probably with springwold asyncapi compatibility mode turn off.

Springwolf generates the asyncapi document, that you http GET, in multiple steps. First, it scans for methods. Then creates the examples (that is the code @sam0r040 changed, as there are json, yaml or xml examples possible, which is independent from the document content type). The examples contain the date strings. Last, you http get the document and use the defaultserializerservice (and its objectmapper).

ccudennec-otto commented 2 months ago

I've just tested the code in Studio and it looks good now! Thanks everyone for your support! 💪

timonback commented 2 months ago

Great, nothing further to do on this issue.

I will re-open the issue for tracking purposes of the next release, and so the maintainers can re-evaluate the compatibility mode introduced in https://github.com/springwolf/springwolf-core/pull/822 for this particular change

github-actions[bot] commented 2 months ago

The change is staged for release and will be part of the next release.

If you want to try and verify it in your application today, use the latest 1.X.0-SNAPSHOT build as described in our README.md > Testing SNAPSHOT version

Thank you for the report/contribution!

timonback commented 1 month ago

After removing the compatibility mode in https://github.com/springwolf/springwolf-core/pull/898, this issue can be closed

github-actions[bot] commented 1 month ago

The change is available in the latest release. 🎉

Thank you for the report/contribution and making Springwolf better!

springwolf / springwolf-core

Easier control over quotes / always quote string values in YAML? #820