Clarification on scan inclusions and exclusions

The MP OpenAPI specification currently defines four configuration keys that deal with including or excluding packages or classes during annotation scanning.

1. mp.openapi.scan.packages - the list of packages to scan
2. mp.openapi.scan.classes - the list of classes to scan
3. mp.openapi.scan.exclude.packages - the list of packages to exclude from scans
4. mp.openapi.scan.exclude.classes - the list of classes to exclude from scans

I would be helpful to (1) explicitly define the precedence for these configurations (and enforce with TCK tests) and (2) define whether the inclusion of a package or exclusion of a package is recursive. Leaving the detail of package recursion as an implementation decision is a problem for portability.

Relates to smallrye/smallrye-open-api#289

[MikeEdgar]

That sounds like a nice idea - and I would even add “or ends with $”. That would give both “starts with” or “ends with” functionality. This can be something we experiment with in SmallRye as well as I don’t think it should break backward compatibility.

[Azquelt]

What was the use case for wanting to be able to use regex here?

My initial thought is that regex seems like a bad fit for matching package names:

1. The . character has a different special meaning in each case
2. Package names are hierarchical and when you’re selecting packages, it’s generally going to be picking subtrees out of this hierarchy, whereas regex is designed for doing complex matching on all sorts of text

I particularly wouldn’t want support for regex to come at the cost of not allowing a more specific match to take priority over a less specific one. Consider the following rules:

• include com.example.a
• exclude com.example.a,b
• include com.example.a.b.c

I think it’s fairly important that these rules have the following result:

• com.example.a.MyClass is included
• com.example.a.b.MyClass is excluded
• com.example.a.b.c.MyClass is included

Implementations are always free to define some way of supporting the use of regex here but I don’t see any need to add it to the spec unless there are clear use cases for it. When we look at the use cases, we might decide for example that a simpler and more restrictive wildcard syntax is more appropriate.