Add support for dependancies with --exclude

[luxaritas]

Is your feature request related to a problem? Please describe.
One of the dependencies in a project I'm working on uses @param <description> to document parameters, which is picked up by swag but fails to parse.

Describe the solution you'd like
I'd like to be able to add this package to the list of ignored directories with --exclude, for example --exclude github.com/owner/package@version

Describe alternatives you've considered

• Requesting the package author to change comment formats (seems inappropriate to put this burden on the maintainer to interop with an external package)

[ubogdan]

@luxaritas It's recommended to write/define your own Request/Response structs and work with that instead of importing them from a third party.
I don't think adding an --exclude will solve the issue you describe; even worse, it will fail to generate it.

[luxaritas]

I'm not intentionally pulling structs from this library - that's the issue. I'm pulling in definitions from dependencies I control, but as part of this process it's also erroneously attempting to parse definitions from a library I don't control

[barnesew]

I had this exact problem as well. I was using the sketches-go library (https://github.com/DataDog/sketches-go) and one of the sub-files (ddsketch/mapping/bit_operation_helper.go) had some @params defined over one of the functions. My problem was fixed when they made a PR that removed the @param annotations from the comments. I wasn't using the library for the request/response structures but swag was following the "--parseDependency" flag and finding the definitions.

[ubogdan]

@barnesew I'm still wondering what will be the expected behavior if one of the ignored paths contains definitions required by the swag parser?

I'm quite busy these days. If any of you can write an implementation, I offer my support regarding code review part.

[kyrozetera]

We ran into this same problem with sketches-go. Unfortunately we depend on another datadog library that depends on a specific version of sketches-go, and the fix hasn't been tagged to a version for the other lib to use. So the only workaround is to either fork the libs ourselves and fix, or set a specific parseDepth and hope that our own dependencies don't get any deeper. We should be able to exclude certain dependencies as suggested, or ignore parse errors from third party dependencies.

[luxaritas]

@ubogdan

I'm still wondering what will be the expected behavior if one of the ignored paths contains definitions required by the swag parser?

It seems to me like that should be up to the user to avoid, right? If you're ignoring a path, it's because it explicitly doesn't comply with swag, so that situation should never happen...?

[ubogdan]

@luxaritas I don't want to spend my life avoiding things.

The exclude flag is a hack that will hide the issue under the table and, in reality, will give more headaches to the project maintainers.

[luxaritas]

Is it a hack? The preferred option is dictating how all dependencies you might use format their docstrings? My knowledge of Go is a bit limited, but this isn't a standard format throughout Go right?

[ubogdan]

I'm not going to argue with anyone here about why is good or bad because different use cases can be better than bad.

You should ask yourself the following questions regarding software development flow:

1. who is the person responsible for updating these include/exclude lists?
2. who and how we are going to test every new exclusion item added didn't break the current API.
3. what is the strategy we are going to follow to ensure the third-party lib didn't suffered a code refactor and moved the "excluded" definition to a new path?

[ubogdan]

Is it a hack? The preferred option is dictating how all dependencies you might use format their docstrings? My knowledge of Go is a bit limited, but this isn't a standard format throughout Go right?

Your app should not use the repository definitions/types in the response models. It's a good practice to build your own DTO (data transfer object) that will be exposed in the API request/response models.