Add support for jsDoc filtering

[identityclash]

This PR allows support for filtering JSDocs through the use of the optional jsDocFilter function in order to selectively output certain documentation of choice.

[kalinchernev]

Hi @identityclash I can't quite understand the scenario this change works on. Could you please clarify and possibly write a test illustrating your point and use case?

[identityclash]

Hi @kalinchernev , sorry for the late reply. I'll get back to you on creating an example for this, as I believe that this could be quite useful especially for a project using swagger-jsdocs that has a single codebase with API documents being selectively (filtered) shown to the different clients using APIs.

Concisely, as an example, say you have 5 APIs for a certain server, using the filtering mechanism in this PR would allow you to show only the first two API documents for client X, and the last three API documents for client Y. Another way would be to allow an mix and match of the API documents to be shown to a particular client.

[identityclash]

Hello @kalinchernev, I appended the manner of usage in the ./example/v2/app.js and ./example/v2/routes2.js. I also added some similarly referencing code in the GETTING-STARTED.md file as an explanation of how they are supposedly used.

The ./example/v2/envVars.js is a new file which is supposed to mimic the environment variables of a certain server.

[etiennea]

I need this too, we have a public and a private api. Would be nice if using tags we could create 2 or more specs.json's

[kalinchernev]

@etiennea it's been quite some time since the last time I put thought on this subject. Glad you bump it, though I can't promise a fast solution, as I don't quite understand the request even after reading through my old comments in the communication above.

As a quick suggestion: you can maybe use https://www.npmjs.com/package/patch-package and modify this function https://github.com/Surnet/swagger-jsdoc/blob/master/src/utils.js#L36 so that you use the swagger-jsdoc package, but have a single place to do if/else logic based on your custom annotations such as @myapi1, @myapi2, etc.

If you also have in mind a way to solve the issue: please go ahead. Current master is for 6.x CommonJS, and 7.x is in RC and can accept breaking changes, more or less the same as 6.x with more tests and ESM. Whichever is more convenient to express suggestions, they are welcome

[stale[bot]]

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.

[stale[bot]]

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.