The Swagger/Javadoc conundrum

conundrum.md

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.)