使用 Javadoc -link 选项链接到 javadoc.io

Question

我正在尝试使用 @link 选项 link 到 javadoc.io 上托管的一些 Java 文档（特别是 PowerMock 的 Java 文档）。我试图将 URL 添加到 PowerMock 的 Java 文档到我的 -link 标志，但无法让 Javadoc 识别它。我将外部 links 用于其他 Java 文档（例如 Guava、Java SE 7），并将 Gradle 作为我的构建系统。我尝试了以下选项：

-link http://static.javadoc.io/org.powermock/powermock-core/1.6.3/

^ 我已经确认在这个目录下有一个package-list文件

-link http://static.javadoc.io/org.powermock/powermock-core/

-link http://javadoc.io/doc/org.powermock/powermock-core/1.6.3/

-link http://javadoc.io/doc/org.powermock/powermock-core/

所有这些都会导致以下错误（URL 相应更改）：

javadoc: warning - Error fetching URL: http://static.javadoc.io/org.powermock/powermock-core/1.6.3/

有人对如何使这项工作有建议吗？

据我所知，这是某种 javadoc.io 特定问题，尽管我这边可能是使用问题 - 例如，我目前使用 -link http://junit.org/javadoc/latest/ 没有问题，但是 -link http://static.javadoc.io/junit/junit/4.12/ 不起作用。

Answer 1

我最后只是使用 -linkoffline 来解决这个问题，我认为它有一个很好的属性在构建时不需要互联网连接，但如果有人对如何与 -link 一起完成这项工作，我洗耳恭听。

Answer 2

很奇怪：我可以在浏览器中看到，例如http://static.javadoc.io/org.pegdown/pegdown/1.6.0/package-list 但是当我将 http://static.javadoc.io/org.pegdown/pegdown/1.6.0 添加为 javadoc 的 link 选项时它说

Error fetching URL: http://static.javadoc.io/org.pegdown/pegdown/1.6.0/package-list

我使用下一个解决方法：

使用 maven-dependency-plugin 解压所需依赖项的 javadoc。

Link 它带有 linkoffline 选项。

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-dependency-plugin</artifactId>
    <version>2.8</version>
    <executions>
        <execution>
            <id>unpack-javadoc</id>
            <phase>package</phase>
            <goals>
                <goal>unpack</goal>
            </goals>
            <configuration>
                <artifactItems>
                    <artifactItem>
                        <groupId>org.pegdown</groupId>
                        <artifactId>pegdown</artifactId>
                        <classifier>javadoc</classifier>
                        <version>${pegdownVersion}</version>
                        <overWrite>false</overWrite>
                        <outputDirectory>${project.build.directory}/pegdown-javadoc</outputDirectory>
                    </artifactItem>
                </artifactItems>
            </configuration>
        </execution>
    </executions>
</plugin>
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <configuration>
        <links>
            <link>http://www.slf4j.org/apidocs/</link>
        </links>
        <offlineLinks>
            <offlineLink>
                <url>http://static.javadoc.io/org.pegdown/pegdown/${pegdownVersion}</url>
                <location>${project.build.directory}/pegdown-javadoc</location>
            </offlineLink>
        </offlineLinks>
    </configuration>
</plugin>

Answer 3

我已经调查了这个问题，这里的问题是必须设置用户代理（空字符串也可以）才能成功完成与 javadoc.io 的连接。

我解决了这个问题并为那些依赖该构建系统的人写了 a Gradle plugin that may be of help。

不幸的是，解决方法无法移植到常规 javadoc -link 命令调用。

Answer 4

在命令行中，使用类似 -J-Dhttp.agent=javadoc.

的参数

在 Maven 中，使用如下内容：

<additionalJOption>-J-Dhttp.agent=maven-javadoc-plugin-${pom‌.name}</additionalJO‌ption>

背景：正如 Danilo Pianini 在 , the problem is the User-Agent header. However, the problem isn't an empty User-Agent; it's the default Java User-Agent 中建议的那样，它看起来像“Java/1.8.0_112”：

$ URL=https://static.javadoc.io/org.checkerframework/checker-qual/2.2.2/package-list

# default Java User-Agent:
$ wget -U Java/1.8.0_112 "$URL" 2>&1 | grep response
HTTP request sent, awaiting response... 403 Forbidden

# no User-Agent:
$ wget -U '' "$URL" 2>&1 | grep response
HTTP request sent, awaiting response... 200 OK

# custom User-Agent:
$ wget -U javadoc "$URL" 2>&1 | grep response
HTTP request sent, awaiting response... 200 OK

所以解决方法是告诉 Javadoc 使用不同的 User-Agent。 Java 不允许您省略 User-Agent，因此您必须提供一个值，该值 Java 将附加到其默认代理。

据我所知，阻止 Javadoc 并不是故意的：Javadoc 只是（可能不明智地）使用默认值 Java User-Agent，并且 javadoc.io 使用的内容分发网络默认会阻止。

（关于 Maven 的更多注意事项：-link 一切正常。如果您下载 package-list 文件并告诉 Javadoc，它也可以与 -linkoffline 正常工作从磁盘读取它。但是，如果您使用 -linkoffline 但告诉 Javadoc 从 javadoc.io URL 中获取 package-list（这是不寻常的事情do), it may fail。问题：Maven 尝试预先验证 package-list 文件，但是在某些版本的 Java 下失败，因为它拒绝 javadoc.io 的 SSL 证书，Javadoc 本身接受的证书。）

（哦，使用 static.javadoc.io 中的 URL 似乎很重要，而不是 javadoc.io。此外，我建议使用 https，而不是 http，以防 http://static.javadoc.io 某天开始向 https://static.javadoc.io 发出重定向，如 Javadoc currently doesn't handle such redirects。此外，https 是一件好事 :))

Answer 5

我是运行javadoc.io。

报这个github issue，刚刚解决了。不再需要覆盖用户代理字符串。

如果仍然无法正常工作，请随时重新打开 github issue。该线程未被主动监控。

curl -I -A "Java/1.6.0_14" https://static.javadoc.io/org.checkerframework/checker-qual/2.2.2/package-list
HTTP/1.1 200 OK
Date: Mon, 08 Apr 2019 13:06:04 GMT
Content-Type: text/plain

使用 Javadoc -link 选项链接到 javadoc.io

Linking to javadoc.io using Javadoc -link option

java

javadoc