如何使生成的类包含XML Schema文档中的Javadoc

Question

我目前正在使用对大多数类型和元素都有<xsd:annotation> / <xsd:documentation>的XML Schema。当我从这个XML Schema生成Java Bean时，那些Beans的Javadoc只包含一些关于类型/元素的允许内容的通用生成信息。

我希望在相关位置看到<xsd:documentation>标记的内容（例如，对于ComplextType，该标记的内容应该显示在为表示该complexType而生成的类的Javadoc中）。

有没有办法实现这个目标？

编辑：此XML Schema将在带有JAX-WS的WSDL中使用，因此该标记也可能是合适的。

编辑2 ：我读过<jxb:javadoc>。根据我的理解，我可以在单独的JAXB绑定文件中或直接在XML Schema中指定。这几乎可以解决我的问题。但我宁愿使用现有的<xsd:documentation>标记，因为Javadoc不是文档的主要目标（主要是关于数据结构的信息，而不是关于从它生成的Java Bean），并允许使用非JAXB工具也可以访问这些信息。提供<jxb:javadoc>和xsd:documentation>中的文档“感觉”错误，因为我没有充分理由重复数据（和工作）。

编辑3 ：感谢Pascal的回答，我意识到我已经有了半个解决方案：<xsd:documentation>的{​​{1}}被写入其Javadoc的开头！问题仍然是仅使用complexType和complexType s（也可能导致类），元素仍然是Javadoc。

Answer 1

我从来没有能够将常规xsd:documentation放在java源代码中，除非当且仅当它是复杂类型。元素的文档，简单类型， 等被忽略。

所以，我最终使用jxb:javadoc。为此，请在xmlns:jxb="http://java.sun.com/xml/ns/jaxb"元素中包含<xsd:schema>的定义。

将儿童添加到<xsd:complexType>或<xsd: element>或<xsd:attribute>：

<xsd:annotation><xsd:appinfo><jxb:XXX><jxb:javadoc>
  This is my comment for a class/property
</jxb:javadoc></jxb:XXX></xsd:appinfo></xsd:annotation>

XXX是“类”或“财产”。

对于一个包，你写一个孩子到xsd:schema

<xsd:annotation><xsd:appinfo><jxb:schemaBindings><jxb:package name="com.acme"><jxb:javadoc>
  This is my comment for a package
</jxb:javadoc></jxb:package></jxb:schemaBindings></xsd:appinfo></xsd:annotation>

撰写HTML文档需要使用<![CDATA[ --- ]]>

进行包围

（编辑：在写我的答案时，问题已由OP编辑，所以我相应地更新了它）

就我而言，javadoc是唯一的目标，所以使用jxb:javadoc是可以接受的。但是你的更新很有意义，实际上，我完全赞同你。可悲的是，我从来没有为你描述的情况找到理想的解决方案（所以我会非常仔细地遵循这个问题）。也许您可以使用xframe之类的内容来生成xsd:documentation的文档，但这不能回答这个问题。

Answer 2

这对于JAXB参考实现是不可能的。即使您尝试编写XJC插件，您也会发现插件API没有引用Schema定义，因此无法提取此信息。

我们唯一的希望是未来版本的JAXB能够解决这个问题。有open feature request here。

Answer 3

特别是在那种情况下，我编写了XJC插件xjc-documentation-annotation-plugin。

它的作用：<annotation><documentation>-> Java类注释

说我们在XSD中描述了这个对象：

<xs:complexType name="CadastralBlock">
    <xs:annotation>
        <xs:documentation>Cadastral quarter</xs:documentation>
    </xs:annotation>
    <xs:sequence>
        <xs:element name="number" type="xs:string">
            <xs:annotation>
                <xs:documentation>Cadastral number</xs:documentation>
            </xs:annotation>
        </xs:element>
</xs:complexType>

我们像这样运行xjc

xjc -npa -no-header -d src/main/generated-java/ -p xsd.generated scheme.xsd

并且得到了类似的类（为简单起见，省略了getters，setters和所有注释）：

public class CadastralBlock {
    protected String number;
}

但是在我的情况下，我想知道如何在源文件中命名类和字段！所以，这个插件可以做什么！

所以您得到：

@XsdInfo(name = "Cadastral quarter", xsdElementPart = "<complexType name=\"CadastralBlock\">\n  <complexContent>\n    <restriction base=\"{http://www.w3.org/2001/XMLSchema}anyType\">\n      <sequence>\n        <element name=\"number\" type=\"{http://www.w3.org/2001/XMLSchema}string\"/></sequence>\n      </restriction>\n  </complexContent></complexType>")
public class CadastralBlock {
    @XsdInfo(name = "Cadastral number")
    protected String number;
}

使用方法

在命令行中手动调用

如果要手动运行，请确保运行类路径中带有插件的jar类，只需添加选项-XPluginDescriptionAnnotation。 F.e。：

xjc -npa -no-header -d src/main/generated-java/ -p xsd.generated -XPluginDescriptionAnnotation scheme.xsd

从Java / Groovy调用

Driver.run(
    [
        '-XPluginDescriptionAnnotation'
        ,'-d', generatedClassesDir.absolutePath
        ,'-p', 'info.hubbitus.generated.test'
        ,'CadastralBlock.xsd'
    ] as String[]
    ,new XJCListener() {...}
)

例如，参见测试XJCPluginDescriptionAnnotationTest。

在Gradle中使用

使用gradle-xjc-plugin：

plugins {
    id 'java'
    id 'org.unbroken-dome.xjc' version '1.4.1' // https://github.com/unbroken-dome/gradle-xjc-plugin
}

...

dependencies {
    xjcClasspath 'info.hubbitus:xjc-documentation-annotation-plugin:1.0'
}

// Results by default in `build/xjc/generated-sources`
xjcGenerate {
    source = fileTree('src/main/resources') { include '*.xsd' }
    packageLevelAnnotations = false
    targetPackage = 'info.hubbitus.xjc.plugin.example'
    extraArgs = [ '-XPluginDescriptionAnnotation' ]
}

在项目example-project-gradle目录中完成gradle示例。