Option to change ParseComment error in dependecies to warning

[matrixik]

Is your feature request related to a problem? Please describe.

swag v1.7.3

I'm using https://github.com/hyperledger/fabric-sdk-go inside my project and in it's dependencies contain some @param comments that doesn't conform to swag format.

In my code I'm importing some of it's types and push them as JSON output to end user.

In my comments I have:

// @Success 200 {object} msp.IdentityResponse{attributes=msp.Attribute}
// @Produce json

If I'm not using --parseDependency true I'm getting error like

2021/09/30 22:30:43 ParseComment error in file /home/zybortd/dev/bc-base-gateway-go/api/http/caadmin/handlers.go :cannot find type definition: msp.IdentityResponse

If I'm using --parseDependency true then msp.IdentityResponse and others are found but swag exit on wrong @param comments:

swag init -dir cmd/server,api/http -o swagger/docs --md swagger/markdown --parseDependency true
2021/09/30 22:26:39 Generate swagger docs....
2021/09/30 22:26:39 Generate general API Info, search dir:cmd/server
2021/09/30 22:26:40 Generate general API Info, search dir:api/http
2021/09/30 22:28:20 Generating msp.IdentityResponse
2021/09/30 22:28:20 Generating msp.Attribute
2021/09/30 22:28:20 Generating msp.IdentityRequest
2021/09/30 22:28:20 ParseComment error in file /home/zybortd/golibs/os/pkg/mod/github.com/hyperledger/fabric-sdk-go@v1.0.0/internal/github.com/hyperledger/fabric-ca/lib/client.go :missing required param comment parameters "req The enrollment request"

Describe the solution you'd like

Option to have errors from dependencies be reported only as warnings and generate properly swagger files.
Or option to avoid parsing comments in dependencies (in my packages included in -dir they would still be parsed strictly).

Describe alternatives you've considered

It's working with swag v1.6.7

swag init -g cmd/server/main.go -o swagger/docs --md swagger/markdown
2021/09/30 23:06:27 Generate swagger docs....
2021/09/30 23:06:27 Generate general API Info, search dir:./
2021/09/30 23:07:40 Generating msp.Attribute
2021/09/30 23:07:40 Generating msp.IdentityRequest
2021/09/30 23:07:40 Skipping 'msp.Attribute', already parsed.
2021/09/30 23:07:40 Generating msp.IdentityResponse
2021/09/30 23:07:40 Skipping 'msp.Attribute', already parsed.
2021/09/30 23:07:40 create docs.go at swagger/docs/docs.go
2021/09/30 23:07:40 create swagger.json at swagger/docs/swagger.json
2021/09/30 23:07:40 create swagger.yaml at swagger/docs/swagger.yaml

and display it properly:

{
  "affiliation": "string",
  "attributes": {
    "ecert": true,
    "name": "string",
    "value": "string"
  },
  "caname": "string",
  "id": "string",
  "maxEnrollments": 0,
  "secret": "string",
  "type": "string"
}

in swag v1.6.5 it's not finding msp.Attribute and showing "Unknown Type: Attribute"

{
  "affiliation": "string",
  "attributes": [
    "Unknown Type: Attribute"
  ],
  "caname": "string",
  "id": "string",
  "maxEnrollments": 0,
  "secret": "string",
  "type": "string"
}

Additional context

I'm aware of #948 but I don't want to add every file from dependencies one by one.

[ubogdan]

@matrixik As far as I can understand, you have three options:

1. make a copy of the structure of msp.Attribute in your API code without `--parseDependency flag. This will give you additional speed when generating the documentation.

2. help us by contributing with a PR for solution solving this issue.

3. use the --exculude flags and suffer in pain :)

[zhwei820]

For those want refer to struct in third package, shell bellow may help (faster than --parseDependency).

go mod vendor && swag init --parseVendor --output api && rm -rf vendor