Convert OpenAPI 3.0 to AsyncAPI 3.0

[jonaslagoni]

This issue is part of a longer vision for the converter that can be found here: #221

It would be great to open up how easily people can switch or try out AsyncAPI based on existing resources. One of these is OpenAPI 3.0: https://spec.openapis.org/oas/v3.0.3. With the new AsyncAPI v3, we should be able to map this 100% from OpenAPI to AsyncAPI.

In order to solve this it requires a lot of conversion that might not be straightforward. While this issue is tagged as a good first issue it requires a lot of effort to push through, on the bright side, solving this issue will help you gain knowledge about OpenAPI and AsyncAPI, and how they relate and differentiate. Of course alongside a huge deal of TS, testing, documentation, and working in Open Source in general.

To make it easier to digest, this issue can be split up into multiple sections to simplify the process of solving this:

1. Step: Convert the following OpenAPI keywords to form a basic AsyncAPI document with no channels nor operations: openapi, info, servers, tags, externalDocs, and security.
2. Step: Convert the OpenAPI paths keyword into channels and operations in AsyncAPI
3. Step: Convert the OpenAPI components into AsyncAPI components

Potential next steps that should NOT be focused on right now

4. Step: Enable multiple options to customize the conversion.
5. Step: Enable the split of the OpenAPI document into one or more AsyncAPI documents.
6. Step: Integrate it into the AsyncAPI CLI to enable faster conversions for users.
7. Write a blog post about this new conversion

NOTICE, because of the difficulty of this issue, you will be able to contact me all the time through Slack if you get stuck solving it at any point and even have calls when relevant.

[aeworxet]

Bounty Issue's service comment

Text labels: bounty/2024-Q2, bounty/advanced, bounty/coding
First assignment to third-party contributors: 2024-03-22 00:00:00 UTC+12:00
End Of Life: 2024-08-31 23:59:59 UTC-12:00

@asyncapi/bounty_team

[AayushSaini101]

@jonaslagoni I am interested in this issue, can you assign to me? Proof of asyncapi/generator#1061 of previous bounty issue

[aeworxet]

@AayushSaini101, taking into account the commit history of PR asyncapi/generator#1061 (your own changes are simple and a lot of coding help is provided by @derberg,) I would propose you to concentrate on only one Bounty Issue of Complexity Level Medium for now, to avoid the risk of misperformance on both Bounty Issues simultaneously and the possibility of receiving an eight-month Suspension for this.

[AayushSaini101]

@AayushSaini101, taking into account the commit history of PR asyncapi/generator#1061 (your own changes are simple and a lot of coding help is provided by @derberg,) I would propose you to concentrate on only one Bounty Issue of Complexity Level Medium for now, to avoid the risk of misperformance on both Bounty Issues simultaneously and the possibility of receiving an eight-month Suspension for this.

Thanks @aeworxet

[alaminthetrustworthy]

Hi, @jonaslagoni can you assign this issue to me.

[jonaslagoni]

@alaminthespecial quick question, how will you approach the task, besides what I already wrote in the issue? 🙂

[alaminthetrustworthy]

@jonaslagoni

• I would study the documentation OpenApi and AsyncApi document and the similarity between them in which format of documents they generate.
• I will explore the converter repo again or any existing repo
• I would start coding your first step which is a conversion of openapi to asyncapi document without operation
• i would write a input (openapi) and output(expected asyncapi v3) test write code similar to the conversion of versions but in this case is for the keywords.

[jonaslagoni]

@alaminthespecial based on your previous contributions and your described approach I don't think it's something you can achieve in the bounty window.

It sounds like there is too much groundwork that needs to be laid before you get to solving the problem at hand 🙂 Please have a look at some of the other issues for bounties ✌️

[alaminthetrustworthy]

Thank you @jonaslagoni but I believe in learning by doing and In my previous contribution I was new to open source could you give me a try .

[jonaslagoni]

@alaminthespecial nothing is stopping you from contributing this, but it will not be as part of the selected bounty program 🙂

[axif0]

hello @jonaslagoni, i want to work on this issue.

[jonaslagoni]

@axif0 as part of the bounty program or regular contribution?

As this issue is harder than regular good-first-issues, I always start by asking how you would approach this issue, to check how much context you have 🙂

[Gmin2]

Hey @jonaslagoni i would like to attempt this

I have prepared an outline for the first objective

Step: Convert the following OpenAPI keywords to form a basic AsyncAPI document with no channels nor operations: openapi, info, servers, tags, externalDocs, and security.

As. openApi 3.0.0 is mostly similar with asyncapi 2.6.0 version i have thought the solution to convert(or use) openAPI to asyncapi 2.6.0 first.

• The asyncapi version string is similar to openapi we just have to rename it.
• The infoobject is similar to asyncapi(2.6.0) info we just have to rename it.
  we can use something like this :)(skip some types here)

interface OpenAPIInfo {
  title: string;
  description?: string;
  termsOfService?: string;
  contact?: OpenAPIContact;
  license?: OpenAPILicense;
  version: string;
}
interface AsyncAPIInfo {
  title: string;
  description?: string;
  termsOfService?: string;
  contact?: AsyncAPIContact;
  license?: AsyncAPILicense;
  version: string;
}

function convertInfo(info: OpenAPIInfo): AsyncAPIInfo {
  return {
    title: info.title,
    description: info.description,
    termsOfService: info.termsOfService,
    contact: info.contact,
    license: info.license,
    version: info.version,
  };
}

• for the server object part
  we can extract url from the protocol:\\+url\+protocolVersion of the openAPI , description and variables remain same .

• security can be extracted from the server object of asyncAPI 2.6.0

• tags remains the same from 3.0.0

• externalDocs remains the same from 3.0.0

[jonaslagoni]

@Gmin2 it will not be impossible to convert OpenAPI to AsyncAPI v2 as they are simply not compatible when it comes to operations, channels, and reply is not even an option.

You are completely right on first step though.

How will you achieve the last two?

Step 2: Convert the OpenAPI paths keyword into channels and operations in AsyncAPI
Step 3: Convert the OpenAPI components into AsyncAPI components

[jonaslagoni]

@Gmin2 please ready through your proposal again and compare it with what is being asked 😅 You are reversing stuff

[Gmin2]

• creating channels
  • for each path in openAPi document , create a corresponding channel in the AsyncAPI document, the channels address keywoard should be extracted from the path string of openAPI.
  • summary,description will come from the channel summary and description
• creating operations
  • for each operation in openAPI file(get,put,post,delete), create a corresponding operation in AsyncAPI document
  • for post operations, set actions to send, and for the rest set it to recieve.
  • set the channel field to a reference object pointing in the corresponding asyncapi channel(eg: ''$ref": "#channels/{channelAddress}"), channelAddress here is the address of the channel created/mapped from openAPI path
  • map the title,summary,description fields from openAPI path.
• messages field can be handled based on the requestBody and responses
  • if openAPi has a requestBody, create a new message defination in the components.message section, message defination will contain headers and payload, headers will be mapped from openAPI requestBody to the AsyncAPI message headers,payload will be mapped from the schema or content from the openAPI requestBody to the asyncapi message payload.
  • add a reference to this message defination in the messages field of the asyncapi
• for the response keywoard , iterate through the responses defined in the openAPI ,for each response create a new message defination in the components.message section.the message section should include headers and payload, the headers will be mapped from the openAPI response to the asyncapi message header, payload will be mapped from the schema/content from the openAPI response to the asyncapi message payload

cc @jonaslagoni

[jonaslagoni]

for post operations, set actions to send, and for the rest set it to recieve.

This is wrong, it will only be receive, if it's from the server's perspective that we generate the AsyncAPI document to document the server as the application.

It will be send for a client application.

This is the tough problem to solve for this entire task ✌️ Might need an option to determine which application you generate for 🙂

@Gmin2 sounds like you are on the right track 💪 Let me know how I can help, and are you looking to solve this under the bounty program or just as a regular contribution?

[Gmin2]

are you looking to solve this under the bounty program or just as a regular contribution?

i would like to solve it under the bounty program
cc @aeworxet

[aeworxet]

Bounty Issue's Timeline

Complexity Level	Assignment date (by GitHub)	Start date (by BP rules)	End date (by BP rules)	Draft PR submission	Final PR submission	Final PR merge
Advanced	2024-05-21	2024-05-27	2024-07-19	2024-06-14	2024-07-05	2024-07-19

Please note that the dates given represent deadlines, not specific dates, so if the goal is reached sooner, it's better.

Keep in mind the responsibility for violations of the Timeline.

[Shurtu-gal]

Might need an option to determine which application you gene

Could use the pointOfViewOption as was done before as well.

[jonaslagoni]

@Shurtu-gal could easily be yea 👍

@Gmin2 do you need anything from me to get started with the first step, or just in general?

[Gmin2]

@Gmin2 do you need anything from me to get started with the first step, or just in general?

going fine will ping you in slack when i need any help

[aeworxet]

@Gmin2, please provide an update to the PR.

[Gmin2]

I need an extension of two weeks for this issue to be completed
@aeworxet

[aeworxet]

Upon request of the Bounty Program Participant (@Gmin2), all remaining target dates of the Bounty Issue's Timeline are extended by two calendar weeks.

Bounty Issue's Timeline Extended

Complexity Level	Assignment date (by GitHub)	Start date (by BP rules)	End date (by BP rules)	Draft PR submission	Final PR submission	Final PR merge
Advanced	2024-05-21	2024-05-27	2024-08-02	2024-06-14	2024-07-05	2024-08-02

Please note that the dates given represent deadlines, not specific dates, so if the goal is reached sooner, it's better.

Keep in mind the responsibility for violations of the Timeline.

[aeworxet]

AsyncAPI Maintainer (@jonaslagoni) delayed response for one period of three consequent working days
#269 (comment)
#269 (review)
so all remaining target dates of the Bounty Issue's Timeline are extended by two calendar weeks.

Bounty Issue's Timeline Extended

Complexity Level	Assignment date (by GitHub)	Start date (by BP rules)	End date (by BP rules)	Draft PR submission	Final PR submission	Final PR merge
Advanced	2024-05-21	2024-05-27	2024-08-16	2024-06-14	2024-07-05	2024-08-16

Please note that the dates given represent deadlines, not specific dates, so if the goal is reached sooner, it's better.

Keep in mind the responsibility for violations of the Timeline.

[jonaslagoni]

Might as well extend it two more weeks @aeworxet unless one of the other maintainers continues the review or it finishes tomorrow, as I will be AFK until the 12th.

[aeworxet]

Upon suggestion of the AsyncAPI Maintainer, who is responsible for the resolution of the Bounty Issue from the AsyncAPI's side (@jonaslagoni), all remaining target dates of the Bounty Issue's Timeline are extended by four calendar weeks.

Bounty Issue's Timeline Extended

Complexity Level	Assignment date (by GitHub)	Start date (by BP rules)	End date (by BP rules)	Draft PR submission	Final PR submission	Final PR merge
Advanced	2024-05-21	2024-05-27	2024-08-30	2024-06-14	2024-07-05	2024-08-30

Please note that the dates given represent deadlines, not specific dates, so if the goal is reached sooner, it's better.

Keep in mind the responsibility for violations of the Timeline.

[asyncapi-bot]

🎉 This issue has been resolved in version 1.5.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀

[jonaslagoni]

Bounty issue completed

[aeworxet]

Bounty Issue Completed 🎉

@Gmin2, please go to the AsyncAPI page on Open Collective and submit an invoice for USD 400.00 with the expense title Bounty converter-js#233, tag bounty, and full URL of this Bounty Issue in the description.