search

bluewave-labs / bluewave-uptime

BlueWave Uptime Monitor application
https://uptime-demo.bluewavelabs.ca/
GNU Affero General Public License v3.0
458 stars 54 forks source link

[Docs] Outdated endpoint documentation #581

Closed mertssmnoglu closed 1 month ago

mertssmnoglu commented 2 months ago

As I realized and @ajhollid mentioned it recently in #569 there are so many route groups, endpoints and every endpoint has it's own body. When some of them is changed, the documentation also needs to be updated.

I want to know what is your ideas and solution advices about this issue. I'm totally open to discussions.

My Ideas/Suggestions

  1. Implementing OpenApi Specifications(swagger) via jsdoc and redirecting people to see OpenApi Specifications
  2. Providing a postman collection and redirecting people to use Postman Collection
  3. Manually updating all of the endpoints

I want to work on this issue.

ajhollid commented 2 months ago

@mertssmnoglu I like the OpenAPI spec so that would be my personal preference.

If you're up to the task we'd love to have your help with it!

Skorpios604 commented 2 months ago

I also like the idea of OpenAPI. It will give us a more automated and in sync documentation with our codebase.

Skorpios604 commented 2 months ago

We already use JSDocs all around our code so the process should be seamless.

mertssmnoglu commented 2 months ago

I was thinking about using swagger-jsdoc and swagger-ui-express but each package looks a bit unmaintained and they comes with some vulnerabilities. You can check the vulnerabilities via npm audit or yarn audit on the source repositories.

20240810_21h43m37s_grim swagger-jsdoc has 77 vulnerabilities

20240810_21h44m41s_grim swagger-ui-express has 3 vulnerabilities

What should we do now?

  1. It doesn't matter, let's implement OpenAPI specs easily with these packages. We will fix security vulnerabilities in the future.
  2. We need to find another packages for making progress.
  3. We shouldn't make this app vulnerable, let's find another solution.
ajhollid commented 2 months ago

I was thinking about using swagger-jsdoc and swagger-ui-express but each package looks a bit unmaintained and they comes with some vulnerabilities. You can check the vulnerabilities via npm audit or yarn audit on the source repositories.

20240810_21h43m37s_grim swagger-jsdoc has 77 vulnerabilities

20240810_21h44m41s_grim swagger-ui-express has 3 vulnerabilities

What should we do now?

  1. It doesn't matter, let's implement OpenAPI specs easily with these packages. We will fix security vulnerabilities in the future.
  2. We need to find another packages for making progress.
  3. We shouldn't make this app vulnerable, let's find another solution.

@mertssmnoglu let's skip the JSdoc library, way that one seems to not be maintained well.

How about generating the documentation first and then we can host it on swagger hub at the very least. Then we can look further into swagger-ui-express and see if we can deal with the vulnerabilities?

mertssmnoglu commented 2 months ago

How about generating the documentation first and then we can host it on swagger hub at the very least. Then we can look further into swagger-ui-express and see if we can deal with the vulnerabilities?

I agree with you. In my next PR, i will create an openapi.json for it.

ajhollid commented 1 month ago

All endpoint docs are up to date now!