Using GitLab tokens from javadoc

Question

We use GitLab with private repos. We also push the Maven sites of those projects to private GitLab pages. Once logged into GitLab, we can access those sites without any issues from our browsers. We have projects having other projects as dependencies, and would like javadoc to link to the Javadoc in the other projects. I have tried a setup in the POM like

  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <configuration>
          <links>
            <link>https://private.gitlab.io/sites/other-project/apidocs/</link>
          </links>
        </configuration>
      </plugin>
    </plugins>
  </reporting>

but this does not work due to missing access. In the GitLab runner, there are various tokens that allow access to GitLab, including the private GitLab pages. But how do I use those tokens from javadoc?

Answer 1

The workaround is to use the -linkoffline javadoc option.

First you will have to create a javadoc artifact in the dependency project, by adding

      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <executions>
          <execution>
            <goals>
              <goal>jar</goal>
            </goals>
          </execution>
        </executions>
      </plugin>

to the build plugins in the POM. This causes the javadoc to be packed in a jar and deployed to the repository in the deploy pahse, along with the other artifacts.

In the dependent project, you will have to unpack the javadoc jar using the dependency plugin

      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <executions>
          <execution>
            <id>unpack-javadoc</id>
            <phase>prepare-package</phase>
            <goals>
              <goal>unpack</goal>
            </goals>
            <configuration>
              <artifactItems>
                <artifactItem>
                  <groupId>mygroup</groupId>
                  <artifactId>dep1</artifactId>
                  <outputDirectory>${project.build.directory}/javadoc/dep1</outputDirectory>
                  <classifier>javadoc</classifier>
                </artifactItem>
              </artifactItems>
            </configuration>
          </execution>
        </executions>
      </plugin>

In the configuration of the javadoc plugin of the dependent project add

<offlineLinks>
  <offlineLink>
    <url>https://mygroup.gitlab.io/wherever/dep1/apidocs/</url>
    <location>${project.build.directory}/javadoc/dep1/</location>
  </offlineLink>
</offlineLinks>

Now, javadoc will use the unpacked javadoc from the dependency to generate the links, and transform them to point to the GitLab site of the dependency. The end user is supposed to have authenticated against GitLab in the browser, so the links can be followed seamlessly.

This actually generates the javadoc twice in the dependency, first as part of the build lifecycle to generate the javadoc jar, and later in the site lifecycle to generate the site/apidocs directory tree that you upload to the site.