search

Surnet / swagger-jsdoc

Generates swagger/openapi specification based on jsDoc comments and YAML files.
MIT License
1.66k stars 224 forks source link

Fix/extract annotations error handling #363

Closed nejclovrencic closed 11 months ago

nejclovrencic commented 1 year ago

When running build, the for loop goes through each file and calls extractAnnotations and executes parsing logic. Any of this logic could throw, for example readFileSync inside extractAnnotations could throw. Currently, this fails the whole process.

This PR wraps everything inside the for loop in a try catch, and throws based on failOnError options.

This PR also replaced eslint-loader because it is deprecated and npm install on master branch currently fails, as eslint-loader does not support eslint v8.

Test plans

1

  1. Add a non-existing file to swagger build configuration
  2. Set failOnError: false
  3. Swagger generation shouldn't fail, if there are other files in the configuration

2

  1. Create a broken symlink (link to a non-existing file)
  2. Include that file in the build configuration
  3. Swagger generation shouldn't fail, if there are other files in the configuration
daniloab commented 1 year ago

@nejclovrencic thanks for the pull request. Some tests break. Can you check it, please?

nejclovrencic commented 1 year ago

@daniloab tests should pass now, audit test was failing because of vulnerability in qs. I have updated express to the latest minor and body-parser to the latest major to fix the vulnerability. It's used only as dev dependency, so shouldn't have any effect in prod.

nejclovrencic commented 1 year ago

@daniloab do you have any ETA when we can get this merged? Can we release a new minor version, including this fix?

daniloab commented 1 year ago

@daniloab do you have any ETA when we can get this merged? Can we release a new minor version, including this fix?

I would like to have a test plan for every merge change. Can we have someone to test your changes? https://dev.to/woovi/test-plan-driven-development-56a2

nejclovrencic commented 1 year ago

@daniloab I have added the test plans in the PR description. I have tested the change, and will ask someone from my team to test this as well.

daniloab commented 1 year ago

@daniloab I have added the test plans in the PR description. I have tested the change, and will ask someone from my team to test this as well.

Sure, I agree. I mean tiny steps: 

1. install the lib
2. try to build with this schema
3. see the error/ 3. see the succes
shekharnwagh commented 1 year ago

I can verify that it works as expected after following the test plan in the PR description. I've created a repo for testing - https://github.com/shekharnwagh/swagger-jsdoc-fix-test.

daniloab commented 1 year ago

I can verify that it works as expected after following the test plan in the PR description. I've created a repo for testing - shekharnwagh/swagger-jsdoc-fix-test.

this is really cool, thanks @shekharnwagh

daniloab commented 1 year ago

is this error expected with the pull request?

Screen Shot 2023-06-02 at 11 57 32
nejclovrencic commented 1 year ago

@daniloabyes, this is expected. There is a broken symlink (src/app.js links to itself), so the library with the PR throws the error. If you change failOnError: false in index.js the code will run without any problems. You can observe similar behaviour even with cat, because the link is broken on purpose, for testing this PR.

> cat src/app.js
cat: src/app.js: Too many levels of symbolic links

> ls -la
total 8
drwxr-xr-x   4 nejclovrencic  staff  128 Jun  5 10:16 .
drwxr-xr-x  10 nejclovrencic  staff  320 Jun  5 10:18 ..
lrwxr-xr-x   1 nejclovrencic  staff    6 Jun  5 10:16 app.js -> app.js
-rw-r--r--   1 nejclovrencic  staff  552 Jun  5 10:16 router.js
shekharnwagh commented 1 year ago

is this error expected with the pull request?

@daniloab I added that symlink to create a scenario where we can test the new failOnError flag.

stale[bot] commented 11 months ago

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

shekharnwagh commented 11 months ago

do you have any ETA when we can get this merged? Can we release a new minor version, including this fix?

@daniloab Would it be possible to merge and release this.

daniloab commented 11 months ago

is this error expected with the pull request?

@daniloab I added that symlink to create a scenario where we can test the new failOnError flag.

can you check the audit flow, please? https://github.com/Surnet/swagger-jsdoc/actions/runs/5763184661/job/15624477586