feat: add help endpoint. #311

princerajpoot20 · 2023-06-14T21:16:56Z

Resloves #144

Description
Adding an endpoint, help/{command}, to return instructions for a given command to the user. For example, help/generate should return available parameters, such as available templates, etc.

To Do

Implement help.controller.ts
Update openapi.yaml
Add unit test for this using Jest and Supertest

closes #144

…ke changes in commands.md file

BOLT04

Looking good @princerajpoot20 , it's a great start 👍
We need some unit tests later too, but for now I've left some feedback to consider.

openapi.yaml

src/controllers/help.controller.ts

BOLT04 · 2023-06-16T21:10:25Z

Also the CI checks are failing, can you look into those later @princerajpoot20 ?

Co-authored-by: David Pereira <didicp4@gmail.com>

princerajpoot20 · 2023-06-18T18:06:32Z

Also the CI checks are failing, can you look into those later @princerajpoot20 ?

Sure, I will take a look at the CI checks @BOLT04

…he path of it

…is pointing to mail cli commands

princerajpoot20 · 2023-06-20T16:30:48Z

Changes

I have changed the parameter passing from the request body to the URL.
The commands file is pointing to the main CLI's usage.md file.

When only help endpoint is called.

`get(help/asyncapi/generate)`

`get(/help/asyncapi/generate/modles/fromTemplate/ASYNCAPI/template)`

Updated openapi.yml file for url path

@BOLT04 Could you please review this.

BOLT04 · 2023-07-08T19:32:08Z

Changes
* I have changed the parameter passing from the request body to the URL.

* The commands file is pointing to the main CLI's usage.md file.
When only help endpoint is called.
### `get(help/asyncapi/generate)` ### `get(/help/asyncapi/generate/modles/fromTemplate/ASYNCAPI/template)` ### get(/help/asyncapi/diff/old/new) # Parameter can also be passed with `" " (space)` in url. #### `get(/help/asyncapi generate modles fromTemplate ASYNCAPI template)` ## The following implementation has two ways of passing parameters in the URL:
* Passing parameters in the URL, separated by `"/"`.

* Passing parameters in the URL, separated by spaces. The whole command, separated by spaces, should be passed after `/help/`.
@BOLT04 Could you please review this.

I'll separate my feedback in sections 🙂.

API response for `/help`

The response for the help endpoint without any parameters can be inspired by the CLI usage documentation. But in our case this is a HTTP API, so the response should have URI links for all available help endpoints. Please change the response that you are using to be appropriate with the API context.

Instead of asyncapi generate, we should have this URI in the response /help/generate. You can make them relative links or absolute links. But if you make them absolute links please don't hardcode "localhost" in the URI 😅. The API in production has the domain api.asyncapi.com, so the absolute URI would be https://api.asyncapi.com/help/generate, and the relative URI would be /help/generate 👍

The API response should be JSON

@princerajpoot20 the screenshots you're sending make it seem the API's response is markdown or something else. They should be JSON like you have on the openapi.yml 😃. For example this information can be deleted:

Also bear in mind @princerajpoot20, we just want this endpoint to be similar to the CLI commands usage, not exactly the same. The information this API endpoint returns needs to be in the context of the server-api, not the CLI. For example the way we use the generate endpoint in the server API is by sending a JSON payload, like this:

{
    "asyncapi": {
        "asyncapi": "2.2.0",
        "info": {
            "title": "Test Service",
            "version": "1.0.0"
        },
        "channels": {}
    },
    "template": "@asyncapi/html-template"
}

So when the help endpoint receives the parameter generate in the URL, the JSON response needs to specify some details like you are already providing (just not in markdown), and then the possible values users can send for each field in the JSON payload of the generate endpoint. For example, for template you would send the enum list that is present on the openapi.yml file of the server-api.
Please take this into consideration for your implementation @princerajpoot20.

URL Parameters can not have spaces

The URLs can't have spaces, but you also shouldn't need to have spaces. Sending generate modles fromTemplate ASYNCAPI template isn't necessary, like I said the help endpoint isn't for the CLI, it's for server-api. So you can just have generate and provide the details about what templates are supported in the JSON response, and what format should be the asyncapi field.

Also, the flags information you are returning isn't applicable for server-api

In general, change the API responses to be in context of server-api, not the CLI commands 🙂

asyncapi-bot · 2023-07-08T19:32:19Z

Hello, @BOLT04! 👋🏼

    I'm 🧞🧞🧞 Genie 🧞🧞🧞 from the magic lamp. Looks like somebody needs a hand!

    At the moment the following comments are supported in pull requests:

    - `/ready-to-merge` or `/rtm` - This comment will trigger automerge of PR in case all required checks are green, approvals in place and do-not-merge label is not added
    - `/do-not-merge` or `/dnm` - This comment will block automerging even if all conditions are met and ready-to-merge label is added
    - `/autoupdate` or `/au` - This comment will add `autoupdate` label to the PR and keeps your PR up-to-date to the target branch's future changes. Unless there is a merge conflict or it is a draft PR.

princerajpoot20 · 2023-07-09T08:56:47Z

The API response should be JSON

@princerajpoot20 the screenshots you're sending make it seem the API's response is markdown or something else. They should be JSON like you have on the openapi.yml 😃. For example this information can be deleted: ![imagem]

Also bear in mind @princerajpoot20, we just want this endpoint to be similar to the CLI commands usage, not exactly the same. The information this API endpoint returns needs to be in the context of the server-api, not the CLI. For example the way we use the generate endpoint in the server API is by sending a JSON payload, like this:
{
    "asyncapi": {
        "asyncapi": "2.2.0",
        "info": {
            "title": "Test Service",
            "version": "1.0.0"
        },
        "channels": {}
    },
    "template": "@asyncapi/html-template"
}
So when the help endpoint receives the parameter generate in the URL, the JSON response needs to specify some details like you are already providing (just not in markdown), and then the possible values users can send for each field in the JSON payload of the generate endpoint. For example, for template you would send the enum list that is present on the openapi.yml file of the server-api. Please take this into consideration for your implementation @princerajpoot20.

@BOLT04 Could you explain this more in detail.

BOLT04 · 2023-07-14T21:17:45Z

The API response should be JSON

@princerajpoot20 the screenshots you're sending make it seem the API's response is markdown or something else. They should be JSON like you have on the openapi.yml 😃. For example this information can be deleted: ![imagem]
Also bear in mind @princerajpoot20, we just want this endpoint to be similar to the CLI commands usage, not exactly the same. The information this API endpoint returns needs to be in the context of the server-api, not the CLI. For example the way we use the generate endpoint in the server API is by sending a JSON payload, like this:
{
    "asyncapi": {
        "asyncapi": "2.2.0",
        "info": {
            "title": "Test Service",
            "version": "1.0.0"
        },
        "channels": {}
    },
    "template": "@asyncapi/html-template"
}
So when the help endpoint receives the parameter generate in the URL, the JSON response needs to specify some details like you are already providing (just not in markdown), and then the possible values users can send for each field in the JSON payload of the generate endpoint. For example, for template you would send the enum list that is present on the openapi.yml file of the server-api. Please take this into consideration for your implementation @princerajpoot20.

@BOLT04 Could you explain this more in detail.

@princerajpoot20 sure, my feedback is on the API's response. We want to provide details about how you'd call these endpoints. For example the generate endpoint, we send the template in the request body to specify the code template we want to generate. The help's API endpoint for generate could be something like this:

{
  "template": [
    "@asyncapi/html-template",
    "@asyncapi/nodejs-template",
    ...
  ]
}

If you're having doubts about how to implement this, ping me on slack 👍

princerajpoot20 · 2023-08-11T15:42:32Z

Hello @BOLT04,

I've implemented the changes we discussed last week, including updating the URL for the AsyncAPI documents. You can check the updated response at this link. I have also added unit tests.

Could you please take a look and provide your feedback?

asyncapi-bot · 2023-08-11T15:42:46Z

Hello, @princerajpoot20! 👋🏼

    I'm 🧞🧞🧞 Genie 🧞🧞🧞 from the magic lamp. Looks like somebody needs a hand!

    At the moment the following comments are supported in pull requests:

    - `/ready-to-merge` or `/rtm` - This comment will trigger automerge of PR in case all required checks are green, approvals in place and do-not-merge label is not added
    - `/do-not-merge` or `/dnm` - This comment will block automerging even if all conditions are met and ready-to-merge label is added
    - `/autoupdate` or `/au` - This comment will add `autoupdate` label to the PR and keeps your PR up-to-date to the target branch's future changes. Unless there is a merge conflict or it is a draft PR.

openapi.yaml

src/controllers/tests/help.controller.test.ts

package.json

openapi.yaml

princerajpoot20 · 2023-08-18T17:30:09Z

@BOLT04
I have made the changes you have mentioned:

add 404 response
refactor: Apply Problem schema
update to the latest version of axios
removed error 422
update schema : HelpListResponse, HelpCommandResponse

Updating the Axios version breaks Jest tests. I found this issue here in axios repo. I discovered that adding the configuration to jest.config.js works fine.

Here are responses of command.

Could you please take a look and provide your feedback whenever you get a moment 🙂

…pCommandResponse, add 404 response, removed error 422

BOLT04

everything looks fine, just one comment regarding the function getting commands 🙂

src/controllers/help.controller.ts

princerajpoot20 · 2023-09-04T20:35:41Z

@BOLT04 I have made the changes. We are now using getAppOpenAPI to obtain the OpenAPI spec.

Here are the updated responses from the help endpoint.

BOLT04

Looks great, awesome job @princerajpoot20 🙂

BOLT04 · 2023-09-07T21:13:37Z

@magicmatatjahu pinging you in case you want to give some feedback on this PR 👍

sonarcloud · 2023-09-09T21:47:24Z

Kudos, SonarCloud Quality Gate passed!

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
0.0% Duplication

BOLT04 · 2023-09-15T21:05:13Z

@princerajpoot20 great job 👍
/rtm

asyncapi-bot · 2023-09-15T21:19:21Z

🎉 This PR is included in version 0.13.0 🎉

The release is available on:

GitHub release
v0.13.0

Your semantic-release bot 📦🚀

princerajpoot20 · 2023-09-16T11:13:53Z

@BOLT04 Thank you for all the help and guidance you provided 🙇🏻‍♂️. I truly appreciate how you took the time to discuss ideas and give me useful feedback. Because of you, I've learned and grown a lot in the process. 🙂

princerajpoot20 added 3 commits June 11, 2023 17:45

Initial Draft for Help Endpoint

78f3dfd

[Update]: Change in the structure, and split will work with space

70d474d

[feat] : Added functionality of fetching data from github repo and ma…

3d0c0c0

…ke changes in commands.md file

princerajpoot20 requested review from smoya, BOLT04, magicmatatjahu and asyncapi-bot-eve as code owners June 14, 2023 21:16

BOLT04 requested changes Jun 16, 2023

View reviewed changes

Update src/controllers/help.controller.ts

58fe75c

Co-authored-by: David Pereira <didicp4@gmail.com>

princerajpoot20 requested a review from BOLT04 June 18, 2023 18:06

princerajpoot20 added 2 commits June 19, 2023 00:12

fix : Improved error handling, added commands.md file and corrected t…

d6879d5

…he path of it

fix: changed the parameter passing from request body to url and file …

bb28c77

…is pointing to mail cli commands

added axios dependency and updated openapi.yml

acc3cd1

princerajpoot20 added 6 commits July 28, 2023 23:45

change response to json formate

993d7ce

Update response and added relative link

3849fb1

Added unit test and update responses

867496d

Used optional chaining to remove code smell

8cbc884

Refactored code for clarity

b44ee3d

Minor changes

5a005f6

BOLT04 requested changes Aug 13, 2023

View reviewed changes

openapi.yaml Show resolved Hide resolved

src/controllers/tests/help.controller.test.ts Outdated Show resolved Hide resolved

package.json Outdated Show resolved Hide resolved

openapi.yaml Outdated Show resolved Hide resolved

openapi.yaml Outdated Show resolved Hide resolved

princerajpoot20 requested a review from BOLT04 August 18, 2023 17:39

princerajpoot20 changed the title ~~feat: improved draft for help endpoint.~~ feat: add help endpoint. Aug 18, 2023

refactor: Apply Problem schema, update schema : HelpListResponse, Hel…

ed228cd

…pCommandResponse, add 404 response, removed error 422

princerajpoot20 force-pushed the improved-draft-help-endpoint branch from f137fdb to ed228cd Compare August 19, 2023 15:56

princerajpoot20 added 2 commits August 19, 2023 21:52

Update version of axios

457bfc9

Minor changes

17f05f8

BOLT04 reviewed Sep 3, 2023

View reviewed changes

src/controllers/help.controller.ts Outdated Show resolved Hide resolved

Used openapi spec from project itself

e747130

BOLT04 previously approved these changes Sep 7, 2023

View reviewed changes

Fix failing checks: lint fix

29bdfca

princerajpoot20 dismissed BOLT04’s stale review via 29bdfca September 8, 2023 17:09

Fix Warning: unsafe regular expression and Object Injection Sink

f381db7

princerajpoot20 requested review from BOLT04 September 9, 2023 13:06

Fix Warnings: Generic Object Injection Sink

7af427c

BOLT04 approved these changes Sep 10, 2023

View reviewed changes

asyncapi-bot added the ready-to-merge label Sep 15, 2023

asyncapi-bot merged commit 81cd935 into asyncapi:master Sep 15, 2023
18 checks passed

asyncapi-bot added the released label Sep 15, 2023

asyncapi-bot removed the ready-to-merge label Sep 28, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add help endpoint. #311

feat: add help endpoint. #311

princerajpoot20 commented Jun 14, 2023 •

edited

BOLT04 left a comment

BOLT04 commented Jun 16, 2023

princerajpoot20 commented Jun 18, 2023

princerajpoot20 commented Jun 20, 2023 •

edited

BOLT04 commented Jul 8, 2023

Changes

When only help endpoint is called.

asyncapi-bot commented Jul 8, 2023

princerajpoot20 commented Jul 9, 2023

The API response should be JSON

BOLT04 commented Jul 14, 2023

The API response should be JSON

princerajpoot20 commented Aug 11, 2023

asyncapi-bot commented Aug 11, 2023

princerajpoot20 commented Aug 18, 2023 •

edited

BOLT04 left a comment

princerajpoot20 commented Sep 4, 2023

BOLT04 left a comment

BOLT04 commented Sep 7, 2023

sonarcloud bot commented Sep 9, 2023

BOLT04 commented Sep 15, 2023

asyncapi-bot commented Sep 15, 2023

princerajpoot20 commented Sep 16, 2023

feat: add help endpoint. #311

feat: add help endpoint. #311

Conversation

princerajpoot20 commented Jun 14, 2023 • edited

BOLT04 left a comment

Choose a reason for hiding this comment

BOLT04 commented Jun 16, 2023

princerajpoot20 commented Jun 18, 2023

princerajpoot20 commented Jun 20, 2023 • edited

Changes

When only help endpoint is called.

get(help/asyncapi/generate)

get(/help/asyncapi/generate/modles/fromTemplate/ASYNCAPI/template)

BOLT04 commented Jul 8, 2023

Changes

When only help endpoint is called.

API response for /help

The API response should be JSON

URL Parameters can not have spaces

asyncapi-bot commented Jul 8, 2023

princerajpoot20 commented Jul 9, 2023

The API response should be JSON

BOLT04 commented Jul 14, 2023

The API response should be JSON

princerajpoot20 commented Aug 11, 2023

asyncapi-bot commented Aug 11, 2023

princerajpoot20 commented Aug 18, 2023 • edited

BOLT04 left a comment

Choose a reason for hiding this comment

princerajpoot20 commented Sep 4, 2023

BOLT04 left a comment

Choose a reason for hiding this comment

BOLT04 commented Sep 7, 2023

sonarcloud bot commented Sep 9, 2023

BOLT04 commented Sep 15, 2023

asyncapi-bot commented Sep 15, 2023

princerajpoot20 commented Sep 16, 2023

princerajpoot20 commented Jun 14, 2023 •

edited

princerajpoot20 commented Jun 20, 2023 •

edited

`get(help/asyncapi/generate)`

`get(/help/asyncapi/generate/modles/fromTemplate/ASYNCAPI/template)`

API response for `/help`

princerajpoot20 commented Aug 18, 2023 •

edited