Unexpected property - channel - on OpenAPI definition

[palazzetti]

Describe the bug A clear and concise description of what the bug is. Starting from version v6.2.0 we're encountering error when deploying to our Azure API Management using generated OpenAPI v3.0 definition. I've tried to copy & paste definition to official online OpenAPI editor - https://editor.swagger.io/ - and we're encountering the following error:

Structural error at 
should NOT have additional properties
additionalProperty: channels
[Jump to line 0]()

Expected behavior We expect to don't have this property at all or being able to opt-in for its usage within library configuration.

Additional context Ending of generated OpenAPI definition is as follow

channels: {}
tags: []

[thorbenandresen]

My temporary work-around:

  const swaggerSpecFixed = swaggerSpec.replace(/channels: {\}\n/, '');

[palazzetti]

My temporary work-around:

  const swaggerSpecFixed = swaggerSpec.replace(/channels: {\}\n/, '');

I've locked "swagger-jsdoc" dependency to version "6.1.0" and it works properly. I think that issue came from latest release which happened 19 hrs ago. Hope in a quick official fix 👍

[daniloab]

My temporary work-around:

  const swaggerSpecFixed = swaggerSpec.replace(/channels: {\}\n/, '');

I've locked "swagger-jsdoc" dependency to version "6.1.0" and it works properly. I think that issue came from latest release which happened 19 hrs ago. Hope in a quick official fix 👍

I will send an official fix to this.

[daniloab]

Now, into version 6.2.0 swagger-jsdoc handles features related to event-driven. So, you can build your XML files by having the path of a channel.

But, a problem related to this is with APIs that do not handle event-driven and do not have these paths into their files.

So, I want to ask you what do you think is the best solution:

• [ ] pass a param into the swagger-jsdoc command line to consider adding channels paths, like yarn swagger-jsdoc --event-driven
• [ ] or just add a check inside the lib that if do not exist channels paths just remove from the final result. What do you think?

[palazzetti]

Hello @daniloab ,

Thank for your feedback. Well, I think that best solution would be the following:

or just add a check inside the lib that if do not exist channels paths just remove from the final result. What do you think?

In that way, you don't need to manage with additional flag neither in CLI nor in npm module usage. if anyone need to use the additional property "channels" it will work out of the box by just adding "channels" to their documentation so I think this as the best solution. Let me know if you agree with me.

Thank you very much,

[daniloab]

Hello @daniloab ,

Thank for your feedback. Well, I think that best solution would be the following:

or just add a check inside the lib that if do not exist channels paths just remove from the final result. What do you think?

In that way, you don't need to manage with additional flag neither in CLI nor in npm module usage. if anyone need to use the additional property "channels" it will work out of the box by just adding "channels" to their documentation so I think this as the best solution. Let me know if you agree with me.

Thank you very much,

I like to go forward with this solution. Also, if someone could feel free to send this pr adding this replace to the final result

[palazzetti]

@thorbenandresen Would you like to send the PR with your solution? If not, I'll send it on your behalf so we could quickly release a patch to library

[baslr]

@daniloab if we look in the openapi 3.0 specification: https://swagger.io/specification/#openapi-object
Fixed Fields ...
This object MAY be extended with Specification Extensions.

This means, there must be no channels field at all.

If channels refer to https://www.asyncapi.com/docs/specifications/v2.3.0
please check for field name asyncapi.
Thank you.

[daniloab]

https://www.asyncapi.com/docs/specifications/v2.3.0

You mean we could look if have the name asyncapi then consider to add the channels?

[baslr]

@daniloab I created a pr #315. This should make everyone happy again 😃

[baslr]

But I think I have to fix something 😅

[daniloab]

fixed into the new release of 6.2.1 version.

[farzadso]

Confirmed this is fixed on 6.2.1.