Swagger-php: Swagger 2.0 - Scan isn't actually excluding any directories passed into "exclude"

[xiehan]

I'm doing the following:

        \Swagger\scan('/srv/', [
            '/srv/identity/v1/',
            '/srv/listening/v1/',
            '/srv/producer/'
        ]);

yet I'm getting this error:

Unexpected field "paramType" for @SWG\Parameter(name="title"), expecting "ref", "parameter", "name", "in", "description", "required", "schema", "type", "format", "items", "collectionFormat", "default", "maximum", "exclusiveMaximum", "minimum", "exclusiveMinimum", "maxLength", "minLength", "pattern", "maxItems", "minItems", "uniqueItems", "enum", "multipleOf", "x" in \ProducerSearchCallback->searchPodcasts() in /srv/producer/callback/ProducerSearchCallback.inc on line 14

A bit of debugging has yielded that the scan() method is indeed failing to ignore anything passed into exclude. I think it's due to an incorrect usage of Symfony's Finder.

(Note that I can probably submit a PR to fix this today, but I figured I'd open a ticket first, just in case I don't manage to make any progress.)

[bfanger]

I'm currious what you're supposed to pass to Finder->exclude().
let me know what you find.

[xiehan]

@bfanger It's definitely lacking in documentation so it took me a while to track down the problem...

Here's what I managed to figure out:

1. Anything passed to exclude() needs to be a relative URL (to whatever was passed to in()). In other words, in my example, I needed to strip out /srv/ from all of the paths in the exclude array.
2. Directories passed to exclude() cannot end in a trailing slash. Considering ending in a trailing slash is fine for in() and this behavior isn't documented anywhere, this can probably be considered a bug in Finder, but I'm also not sure it's truly worth opening a ticket with them about. (Let me know if you think this is worth doing though.)
3. You can only pass in directories to exclude(), not single files. After many trials and failures, I figured out that you have to use notPath() for single files. Again, notPath() needs to be relative to whatever got passed into in().

The question now is: should we have Swagger-PHP try to handle these situations more gracefully (by eg. forcing exclude URLs to be relative to the director(y/ies) passed in and stripping trailing slashes) or do we just expect users to pass paths to exclude() in the format Finder seems to expect (by adding documentation rather than code)?

Either way, if you want to support excluding single files, there will be some code that needs to be added. I'm available to make these code changes, but let me know how you want to handle the situation in the previous paragraph.

[amreladawy]

@xiehan are the paths passed to exclude() still relative to the in() folder?

 if ($exclude !== null) {
            if (is_string($exclude)) {
                $finder->notPath(Util::getRelativePath($exclude, $directory));
            } elseif (is_array($exclude)) {
                foreach ($exclude as $path) {
                    $finder->notPath(Util::getRelativePath($path, $directory));
                }
            } else {
                throw new InvalidArgumentException('Unexpected $exclude value:' . gettype($exclude));
            }
        }

From the finder() method in Util.php looks otherwise.

[ogwugo]

insteadd of excluding, why not include. take array of the folders you want.

  $swagger = \OpenApi\scan(['/application','/app']);

[zl-kolev]

@ogwugo, that answer saved me today!