Okay folks, I've been digging deeper into this problem this morning. The crux of the issue is that swagger-codegen-maven-plugin generates
its sources in target/generated-sources/src
and when the "site" phase runs to create the repositories website (including the javadocs), those sources are considered part of the set that are candidates for inclusion in the javadocs.
However, using <excludePackageNames>
is of no help. For one,
target.generated-sources.swagger.src.gen.java.main.*
is invalid because a package name cannot contain a hyphen. Try it! Make this source file:
import target.generated-sources.whatever;
class Foo {
public static void main(String[] argv) throws Throwable {
System.out.println("🤌");
}
}
The compiler will complain:
Foo.java:1: error: ';' expected
import target.generated-sources.whatever;
^
1 error
Secondly, Maven can't find those packages to exclude because to Maven, all source files are under src
, not target/generated-sources/src
. So the javadoc plugin generates a packages
file that will always include:
target.generated-sources.swagger.src.gen.java.main.gov.nasa.pds.api.base
target.generated-sources.swagger.src.gen.java.main.gov.nasa.pds.model
target.generated-sources.swagger.src.gen.java.main.io.swagger
target.generated-sources.swagger.src.gen.java.main.io.swagger.configuration
gov.nasa.pds.api.base
gov.nasa.pds.model
io.swagger
io.swagger.configuration
api.pds.nasa.gov.api_search_query_lexer
gov.nasa.pds.api.registry.lexer
gov.nasa.pds.api.model.xml
…
The fix should be to tell Javadoc that it has multiple source directories:
<sourcepath>${project.basedir}/src/main/java:${project.basedir}/lexer/target/generated-sources:${project.basedir}/lexer/target/generated-test-sources:${project.basedir}/model/target/generated-sources:${project.basedir}/service/target/generated-sources:${project.basedir}/service/target/generated-test-sources</sourcepath>
<excludePackageNames>io.swagger.*</excludePackageNames>
But this doesn't seem to cut it either—and I can't fathom why.
The only way I've worked around this is to make my own javadoc
that filters out any Swagger and generated sources. I renamed the javadoc
command to javadoc.orig
and installed this shell script in its place:
#!/bin/sh
javadoc=/usr/lib/jvm/java-11-openjdk/bin/javadoc.orig
# Is there a @packages argument?
for arg in "$@"; do
if [ "x$arg" = "x@packages" ]; then
# Yes, filter out generated-sources
sed -i.orig /generated-sources/d /io\.swagger/d $PWD/packages
fi
done
exec $javadoc "$@"
Now, when Maven executes javadoc
, this script removes the offensive items and then invokes the real javadoc.
The problem goes away! (Except that there are then other issues with the docs that occur later on, but that's for another day.)