chore: refactor helpers

[kalinchernev]

Reorganizing code by modules related to their purpose, which makes the specification-related utils easier to manage in 1 place.
Other helpers have also been reorganized into combined modules, which makes it easier to mock selected functions within modules.

BREAKING CHANGES

• The support for deprecated properties has been removed. Please use the plural form. This support for deprecated properties has lasted for 4 years.
• Upgraded to Erbium (LTS)

[arizonatribe]

https://github.com/Surnet/swagger-jsdoc/blob/master/lib/helpers/specification.js#L55 is a dead link

[sibelius]

what about using Typescript?

[arizonatribe]

Because of the way people use leading wildcards in their package.json it will cause the docs to not be picked up at all on one machine running 4.3.2 and still work on another one running 4.3.0. This is what happened to us and we wasted an hour of work trying to figure out what was wrong.

It's a good idea to wait until a major release to introduce a change like removing support for the deprecated tags. In the future can you please use proper semantic versioning practices and not introduce a breaking change on a patch release? At the very least you can do a minor release (ideally it would have been better to introduce this breaking change in a major release).

[kalinchernev]

Apologies for the dead link, here it is

swagger-jsdoc/lib/helpers/specification.js

Line 55 in b95f784

function getSwaggerSchemaWrongProperties() {

Not sure what you mean with the feedback regarding semantic versioning.
For this particular breaking change, there is a major bump https://www.npmjs.com/package/swagger-jsdoc/v/5.0.0 and a corresponding release https://github.com/Surnet/swagger-jsdoc/releases/tag/v5.0.0 What is not semantic about this?

Because of the way people use leading wildcards in their package.json

You can change this in order to not get major releases before you prepare for them.

[arizonatribe]

Correct. If I'm not prepared for breaking changes in major release v5 then I can remain on v4 through the use of the proper wildcard.

For that to work it is important that the package author not introduce a breaking change in version 4. That is what we encountered on 4.3.2.

The dropping of support for those deprecated singular tag names should have waited until version 5. But because you introduced them in a "patch" version it makes it so that we receive that breaking change before we are ready for it. And the only way to guard against that now is to lock in to exactly version 4.3.0.

Changes that drop support for certain features - which have worked all throughout an entire major version - are not meant for a patch version (ie, a release which increments only the final digit in the version of a package.json). Package consumers rely on these concepts being observed for semantic versioning to work as intended.

[kalinchernev]

@arizonatribe thank you for the elaborate explanation.

The mistake comes from the automated publishing script bumping patch instead of a breaking change. Keywords not detected and thus the lack of correct version.

Apologies once again.

[arizonatribe]

Okay I understand. Thank you for replying. I appreciate the work you do on this project

[kalinchernev]

I thank YOU for reporting the issue! I added warning on the tag here on github with reference to the discussion for the others who might have the same issue. I hope it'll be the less harm than unpublishing the wrong version from npm...

Many thanks and apologies for the time wasted on this!

PS Major bumps will be done manually in the future