Convert OpenAPI 3.0 to AsyncAPI 3.0

jonaslagoni commented 6 months ago

This issue is part of a longer vision for the converter that can be found here: https://github.com/asyncapi/converter-js/issues/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:

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

Potential next steps that should NOT be focused on right now

Step: Enable multiple options to customize the conversion.
Step: Enable the split of the OpenAPI document into one or more AsyncAPI documents.
Step: Integrate it into the AsyncAPI CLI to enable faster conversions for users.
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 commented 6 months ago

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 commented 6 months ago

@jonaslagoni I am interested in this issue, can you assign to me? Proof of https://github.com/asyncapi/generator/pull/1061 of previous bounty issue

aeworxet commented 6 months ago

@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 commented 6 months ago

@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 commented 6 months ago

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

jonaslagoni commented 6 months ago

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

alaminthetrustworthy commented 6 months ago

@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 commented 6 months ago

@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 :v:

alaminthetrustworthy commented 6 months ago

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 commented 6 months ago

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

axif0 commented 5 months ago

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

jonaslagoni commented 5 months ago

@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 commented 4 months ago

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 commented 4 months ago

@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 commented 4 months ago

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

Gmin2 commented 4 months ago

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 commented 4 months ago

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 :v: Might need an option to determine which application you generate for :slightly_smiling_face:

@Gmin2 sounds like you are on the right track :muscle: 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 commented 4 months ago

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 commented 4 months ago

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 commented 4 months ago

Might need an option to determine which application you gene

Could use the pointOfViewOption as was done before as well.

jonaslagoni commented 4 months ago

@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 commented 4 months ago

@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 commented 3 months ago

@Gmin2, please provide an update to the PR.

Gmin2 commented 2 months ago

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

aeworxet commented 2 months ago

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 commented 2 months ago

AsyncAPI Maintainer (@jonaslagoni) delayed response for one period of three consequent working days https://github.com/asyncapi/converter-js/pull/269#issuecomment-2254524415 https://github.com/asyncapi/converter-js/pull/269#pullrequestreview-2209468296 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 commented 2 months ago

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 commented 1 month ago

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 commented 1 month ago

:tada: This issue has been resolved in version 1.5.0 :tada:

The release is available on:

Your semantic-release bot :package::rocket:

jonaslagoni commented 1 month ago

Bounty issue completed

aeworxet commented 1 month ago

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.

asyncapi / converter-js