feat: toc and operation reply

[korifey91]

Description

• fix the TOC(Table Of Content) issue
• fix the operation reply issue
• add new helper class and tests for it

Notes:

• Someone needs to take a look at the tests, as some previous test snapshots are incorrect.

If you are interested in this pull request, please guide me on how we can merge it.

Related issue(s)
Resolves #454, #452

[github-actions]

Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[korifey91]

/ptal

[asyncapi-bot]

@fmvilas @derberg @magicmatatjahu Please take a look at this PR. Thanks! 👋

[derberg]

@honnel @CodeGlitcher please join review at least as end users, not for code.

Just grab this PR and run generation locally with your files and share feedback

instead of usual @asyncapi/markdown-template you just need to put https://github.com/korifey91/async-api-markdown-template

[honnel]

@honnel @CodeGlitcher please join review at least as end users, not for code.

Just grab this PR and run generation locally with your files and share feedback

instead of usual @asyncapi/markdown-template you just need to put https://github.com/korifey91/async-api-markdown-template

Generated TOC looks good to me, nice work! 🎉

[CodeGlitcher]

I rendered a preview of our asycn api documents and it looks good to us.
This would certainly help automate our api documentation in a readable format.

[derberg]

v2 did not support request/reply pattern, so we really need to stick to publish/subscribe always, no request/reply

what I mean is that in case of v2 it is either publish or subscribe and I believe operation.reply() is anyway always undefined in v2

not sure if you are familiar in v2

so in v2 spec, we had publish/subscribe from perspective of the user of the API. So if AsyncAPI document for service A had publish operation - then it meant that end user can send a message, and service A in fact subscribes to a message. Same around, if service A had subscribe operation, it meant that user can subscribe so the service A was in fact publishing. Yeah, confusing, thus we changed it

in v3 we say what API does, so send means API sends and receive means API receives - as simple as that.

REQUEST: 'request' should be publish
REPLY: 'request' should be subscribe

any anyway, they will never be use as in v2, reply is always undefined

[korifey91]

Thank you for detailed comment! I appreciate it.
I'll fix types.

[derberg]

@korifey91 lemme know whenever you're ready for next review

[korifey91]

@derberg I'm ready. Take a look, please

[derberg]

@korifey91 I changed pr prefix to feat as we need to release it as minor not patch

please have a look into failing tests

[korifey91]

@korifey91 I changed pr prefix to feat as we need to release it as minor not patch

please have a look into failing tests

We need someone we can trust to check the tests and ensure they are accurate. There are some issues with the snapshots that seem incorrect to me, as they do not contain the necessary information.

For example,

Operations component › for AsyncAPI v3 › should render reply operation

    expect(received).toMatchSnapshot()

    Snapshot name: `Operations component for AsyncAPI v3 should render reply operation 1`

    - Snapshot  -  1
    + Received  + 21

    @@ -40,6 +40,26 @@
      ```


      #### Response information

    - *  should be done to channel: `user/signedup`
    + * reply should be done to channel: `user/signedup`
    + #### Message `SomeReplyMessage`
    +
    + A longer description of the message
    +
    + ##### Payload
    +
    + | Name | Type | Description | Value | Constraints | Notes |
    + |---|---|---|---|---|---|
    + | (root) | object | - | - | - | **additional properties are allowed** |
    + | user | string | - | - | - | - |
    + | signup | number | - | - | - | - |
    +
    + > Examples of payload _(generated)_
    +
    + ```json
    + {
    +   "user": "string",
    +   "signup": 0
    + }
    + ```

As we can see here it expects one line of a text(which seems incorrect to me). There are fails with the same problems.

Except one, with a new CommonHelpers.isV3 method fail. There is a problem with a tested AsyncAPIDocument which doesn't have required version info(it is undefined there). But parser docs says that it can't be undefined.

[korifey91]

@derberg If you trust me, I can override snapshots and fix the test with CommonHelpers.isV3 function in TableOfContents.test.js

[derberg]

yeah, they are human readable, so just update and push to PR and I will see what changed, no worries

[sonarcloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
No data about Duplication

See analysis details on SonarCloud

[korifey91]

@derberg done, please take a look

[derberg]

LGTM! Thanks @korifey91 a 💯 if only all PR were on such good quality level!

@honnel @CodeGlitcher would it be a lot if I ask you again to test this PR 🙏🏼 there was some refactoring done after you had a look. Snapshots look good to me, but better double check 😄

[derberg]

ok, looks like people do not have more feedback to share

thanks @korifey91 again

[derberg]

/rtm

[derberg]

@allcontributors please add @korifey91 for code,test

[allcontributors]

@derberg

I've put up a pull request to add @korifey91! 🎉

[derberg]

dependabot is such an ass..... pushed updates while release pipeline was in progress, and blocked release :(

[derberg]

@korifey91 maybe you would be willing to open another quick fix PR for #365 and then we would trigger release again

[korifey91]

@korifey91 maybe you would be willing to open another quick fix PR for #365 and then we would trigger release again

I'll take a look and try to find some time for fix

[asyncapi-bot]

🎉 This PR is included in version 1.6.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀