Am I the only one who doesn't understand includes and excludes? :-)

[cristalp]

I'm experimenting with the plugin together with scanPackages, scanClasses, scanExcludePackages and scanExcludeClasses.

I don't understand the concept, it seems. The documentation states that this is a regex.

So I want to ignore the package foo.bar.baz and its subpackages. I then configure the following:

<scanExcludePackages>foo.bar.baz</scanExcludePackages>

This works, but it's not really a regex :-) The correct way, which also works, is

<scanExcludePackages>foo\.bar\.baz</scanExcludePackages>

This also seems to work:

<scanExcludePackages>^foo\.bar\.baz$</scanExcludePackages>

However, this doesn't work:

<scanExcludePackages>foo.bar.baz.*</scanExcludePackages>

And neither this:

<scanExcludePackages>foo.*.baz</scanExcludePackages>

IMHO these are all regexes which should work.

Next I tried several packages. Since it's a regex, this should work, but it doesn't:

<scanExcludePackages>(foo.bar.baz|my.nice.package)</scanExcludePackages>

No, I have to use a comma-separated list:

<scanExcludePackages>foo.bar.baz,my.nice.package</scanExcludePackages>

Clearly, this is not a regex. I think the documentation is not clear enough what is meant by "regex".

[MikeEdgar]

@cristalp , regex mode is only enabled when the properties start with ^ and end with $. Otherwise, this is from the MP OpenAPI specification [1]:

The following rules are used to determine whether a class is scanned for annotations:

1. A class is not scanned if it’s listed in mp.openapi.scan.exclude.classes

2. A class is scanned if it’s listed in mp.openapi.scan.classes

3. A class is not scanned if its package, or any of its parent packages are listed in mp.openapi.scan.exclude.packages, unless a more complete package or parent package is listed in mp.openapi.scan.packages

4. A class is scanned if its package or any of its parent packages are listed in mp.openapi.scan.packages

5. A class is scanned if mp.openapi.scan.classes and mp.openapi.scan.packages are both empty or not set

Can you point to the documentation you mentioned about using regular expressions?

[1] https://download.eclipse.org/microprofile/microprofile-open-api-3.1.1/microprofile-openapi-spec-3.1.1.html#_core_configurations

[cristalp]

Thanks for the clarification!

What I meant was the Maven plugin documentation: https://github.com/smallrye/smallrye-open-api/tree/main/tools/maven-plugin

[MikeEdgar]

What I meant was the Maven plugin documentation

Ah, right! I should have guessed by the XML properties 😄

[cristalp]

So, have other people had the same problems as me? I mean, is it just me or is the documentation not clear enough?

[MikeEdgar]

It doesn't come up often, but it may depend on how complex others' requirements for including and excluding may be. The documentation could certainly be improved, and contributions in that area are always welcome. Often we don't know things are not clear without feedback or suggestions.

If you're open to submit PR(s) with improvements, that would certainly be very much appreciated!

[cristalp]

Ok, I will try. Be gentle with me, because this will be my first pull request :-)

[cristalp]

Pull request: #1958