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

Question

我试图使用该@link选项链接到javadoc.io(特别是PowerMock的Javadocs)托管的一些Javadoc .我试图将PowerMock的Javadocs的URL添加到我的-link标志中,但无法让Javadoc识别它.我正在使用外部链接到其他Javadocs(例如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

从命令行,使用像这样的参数-J-Dhttp.agent=javadoc.

在Maven中,使用以下内容:

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

背景:正如Danilo Pianini在另一个答案中建议的那样,问题就是User-Agent标题.但问题不是空洞的 User-Agent ; 它是默认的JavaUser-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.-linkoffline如果你下载package-list文件并告诉Javadoc从磁盘读取它也可以正常工作.但是,如果你使用-linkoffline但告诉Javadoc package-list从javadoc.ioURL 获取(这是一个不寻常的事情)这样做),这可能会失败的问题:Maven的尝试预验证package-list文件,但下的Java的一些版本,因为它拒绝的SSL证书失效javadoc.io,即自身的Javadoc接受证书).

(哦,看起来重要的是使用特定的URL static.javadoc.io,而不是javadoc.io.另外,我建议https,不是http,以防http://static.javadoc.io有一天开始发布重定向https://static.javadoc.io,因为Javadoc 目前不处理这样的重定向.此外,https是一件好事:))

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选项时，它说

提取URL时出错：http : //static.javadoc.io/org.pegdown/pegdown/1.6.0/package-list

我使用下一个解决方法：

1. 与maven-dependency-pluginunapack所需依赖项的javadoc。

2. 将其与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>