CXF wsdl2java 不为成员生成 Javadoc

Question

从 CXF 2.7.5 运行 wsdl2java 类似

<xsd:complexType name="baseTaxParametersEnhanced">
  <xsd:annotation>
    <xsd:documentation>
      Some type comment.
    </xsd:documentation>
  </xsd:annotation>
  <xsd:sequence>
    <xsd:element name="municipality" type="xsd:string">
      <xsd:annotation>
        <xsd:documentation>
          Some member comment.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:element>
    <xsd:element name="zip" type="xsd:string" />

为BaseTaxParametersEnhanced 类而不是municipality 成员生成Javadoc。

这出乎意料，我没有在文档中看到用于打开/关闭此功能的标志？

Answer 1

关于 xjc-javadoc-plugin。正如项目页面上所写：“插件已被纳入 Apache CXF XJC Utils”。 尽管在https://cxf.apache.org/xjc-utils.html 页面上对此一无所知。但它在那里并作为“基于 xsd:documentation 元素添加 javadocs”。对于使用“来自 Apache”的插件：

<plugin>
  <groupId>org.apache.cxf</groupId>
  <artifactId>cxf-codegen-plugin</artifactId>
  <version>3.3.5</version>
  <executions>
    <execution>
      <!-- ... -->
      <configuration>
        <wsdlOptions>
          <wsdlOption>
            <!-- ... -->
            <extraargs>
              <extraarg>-xjc-Xjavadoc</extraarg>
            </extraargs> 
          </wsdlOption>
        </wsdlOptions>
      </configuration>
    </execution>
  </executions>
  <dependencies>
    <dependency>
      <groupId>org.apache.cxf.xjcplugins</groupId>
      <artifactId>cxf-xjc-javadoc</artifactId>
      <version>3.3.1</version>
    </dependency>
  </dependencies>
</plugin>

或

<plugin>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-xjc-plugin</artifactId>
    <version>3.3.1</version>
    <configuration>
        <extensions>
            <extension>org.apache.cxf.xjcplugins:cxf-xjc-javadoc:3.3.1</extension>
        </extensions>
    </configuration>
    <executions>
        <execution>
            <!-- ... -->
            <configuration>
                <!-- ... -->
                <xsdOptions>
                    <xsdOption>
                        <!-- ... -->
                        <extensionArgs>-Xjavadoc</extensionArgs>
                    </xsdOption>
                </xsdOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

Answer 2

不幸的是，几乎没有什么办法可以轻松修复它。 wsdl2java 在底层使用 xjc 来生成类。为此提出了一个老问题 (JAXB-172)。你可以投票给它。没有 xjc 插件可以解决这个问题。 How to make generated classes contain Javadoc from XML Schema documentation 中提到了有关此问题的更多信息。

如那里所述，如果您可以控制 WSDL/XSD 文件，则可以将 xsd:documentation 替换为嵌入式自定义绑定 (jxb:javadoc)。为此，您应该声明 jxb 命名空间，例如：

<xsd:schema ... xmlns:jxb="http://java.sun.com/xml/ns/jaxb">

并更改您的类型声明：

<xsd:complexType name="baseTaxParametersEnhanced">
    <xsd:annotation>
        <xsd:appinfo>
            <jxb:class>
                <jxb:javadoc>Some type comment.</jxb:javadoc>
            </jxb:class>
        </xsd:appinfo>
    </xsd:annotation>
    <xsd:sequence>
        <xsd:element name="municipality" type="xsd:string">
            <xsd:annotation>
                <xsd:appinfo>
                    <jxb:property>
                        <jxb:javadoc>Some member comment.</jxb:javadoc>
                    </jxb:property>
                </xsd:appinfo>
            </xsd:annotation>
        </xsd:element>
        <xsd:element name="zip" type="xsd:string" />
    </xsd:sequence>
</xsd:complexType>

这个解决方案的问题是这些 cmets 不会被其他 WSDL/XSD 工具识别。

如果您无法控制 WSDL/XSD，您也可以使用外部 JAXB 绑定来做同样的事情，但这似乎开销太大。

如果可以，请对提到的问题进行总结。也许有一天有人决定是时候实现该功能了。

编辑

因为我认为不能使用 XJC 插件来执行这样的任务很奇怪（提到的问题中的一个 cmets 指出），所以我决定尝试编写这样的插件。

结果可以在这里找到： https://github.com/destin/xjc-javadoc-plugin

目前它仅将 cmets 添加到复杂类型的字段（不是 getter 或 setter）。如果您有任何改进建议，我将不胜感激。当我认为它足够稳定时，我会尝试将其贡献给 CXF 项目，以便任何人都可以轻松使用它。