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

Question

提问by Joachim Sauer

I'm currently working with an XML Schema that has <xsd:annotation>/<xsd:documentation>on most types and elements. When I generate Java Beans from this XML Schema, then the Javadoc of those Beans only contains some generic generated information about the allowed content of the type/element.

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

I'd like to see the content of the <xsd:documentation>tag in the relevant places (for example the content of that tag for a complextType should show up in the Javadoc of the class generated to represent that complexType).

我想<xsd:documentation>在相关位置查看标记的内容（例如，complextType 的标记内容应显示在生成的类的 Javadoc 中，以表示该 complexType）。

Is there any way to achieve this?

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

Edit: this XML Schema will be used in a WSDL with JAX-WS, so this tag might be appropriate as well.

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

Edit 2: I've read about <jxb:javadoc>. From what I understand I can specify that either in a separate JAXB binding file or directly in the XML Schema. That would almost solve my problem. But I'd rather use the existing <xsd:documentation>tag, since Javadoc is not the primary target of the documentation (it's information about the data structure primarily and not about the Java Beans generated from it) and to allow non-JAXB tools to access the information as well. Providing the documentation in both <jxb:javadoc>and xsd:documentation>"feels" wrong, because I'm duplicating data (and work) for no good reason.

编辑 2：我读过关于<jxb:javadoc>. 据我所知，我可以在单独的 JAXB 绑定文件中或直接在 XML 模式中指定。那几乎可以解决我的问题。但我更愿意使用现有的<xsd:documentation>标签，因为 Javadoc 不是文档的主要目标（它主要是关于数据结构的信息，而不是关于从它生成的 Java Beans）并允许非 JAXB 工具访问信息作为好。提供文档<jxb:javadoc>和xsd:documentation>“感觉”是错误的，因为我无缘无故地复制数据（和工作）。

Edit 3: Thanks to the answer by Pascal I realized that I already have half a solution: The <xsd:documentation>of complexTypes is written to the beginning of its Javadoc! The problem is still that onlythat complexTypes is used and simpleTypes (which can also result in a class) and elements are still Javadoc-less.

编辑3：多亏了帕斯卡尔我的答案意识到，我已经有半个解决方案：<xsd:documentation>的complexTypes的写入它的Javadoc的开始！问题仍然是只有该complexTypeS用于和simpleTypeS（这也可导致在一个类）和元素仍然Javadoc的更小。

Answer 1

采纳答案by Pascal Thivent

I've never been able to get regular xsd:documentationto be placed in the java source except if and only ifit was a Complex Type. Documentation for elements, simple types, etc are ignored.

我从来没有能够得到规则xsd:documentation被放置在不同的Java源代码当且仅当它是一个复杂的类型。元素、简单类型等的文档被忽略。

So, I end up using jxb:javadoc. To do so, include the definition of xmlns:jxb="http://java.sun.com/xml/ns/jaxb"in your <xsd:schema>element.

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

Add a child to <xsd:complexType>or <xsd: element>or <xsd:attribute>:

孩子添加到<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>

Where XXX is either "class" or "property".

其中 XXX 是“类”或“财产”。

For a package you write a child to xsd:schema

对于你写一个孩子的包 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>

Writing HTML document requires bracketing with <![CDATA[ --- ]]>

编写 HTML 文档需要用括号括起来 <![CDATA[ --- ]]>

(EDIT: While writing my answer, the question has been edited by the OP so I'm updating it accordingly)

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

In my case, javadoc was the only target so it was acceptable to use jxb:javadoc. But your update makes perfect sense and, actually, I totally agree with you. Sadly, I never found an ideal solution for the situation you describe (so I'll follow this question very carefully). Maybe you could use something like xframeto generate documentation from xsd:documentation, but this doesn't answer the question.

就我而言，javadoc 是唯一的目标，因此使用jxb:javadoc. 但是您的更新完全有道理，实际上，我完全同意您的看法。可悲的是，我从来没有为您描述的情况找到理想的解决方案（所以我会非常仔细地关注这个问题）。也许您可以使用xframe 之类的东西从生成文档xsd:documentation，但这并不能回答问题。

Answer 2

回答by skaffman

This just isn't possible with the JAXB reference implementation. Even if you were to try to write an XJC plugin, you'd find that the plugin API is given no reference to the Schema definition, so there's no way to extract this information.

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

Our only hope is that a future version of JAXB fixes the situation. There's an open feature request here.

我们唯一的希望是 JAXB 的未来版本可以解决这个问题。这里有一个开放的功能请求。

Answer 3

回答by John Spragge

I find the following techniques work pretty well for adding JavaDoc headers to Java element classes (generated from XML schemas). I nest the JavaDoc in tags defined in the jax-b namespace, nested within the xml schema annotation and appinfo tags. Note the jaxb namespace defines types of documentation tags; I use two of there: the class and the property tags. defined in the following namespace: xmlns:jxb="http://java.sun.com/xml/ns/jaxb"

我发现以下技术非常适合将 JavaDoc 标头添加到 Java 元素类（从 XML 模式生成）。我将 JavaDoc 嵌套在 jax-b 命名空间中定义的标记中，嵌套在 xml 模式注释和 appinfo 标记中。注意 jaxb 命名空间定义了文档标签的类型；我在那里使用两个：类和属性标签。在以下命名空间中定义： xmlns:jxb="http://java.sun.com/xml/ns/jaxb"

1) To document a class, I use a jaxb "class" tag in the following sequence:

1) 为了记录一个类，我按以下顺序使用了一个 jaxb“class”标签：

  <xs:complexType name="Structure">
     <xs:annotation>
        <xs:appinfo>
           <jxb:class>
              <jxb:javadoc>
                 Documentation text goes here. Since parsing the schema  
                 into Java involves evaluating the xml, I escape all 
                 the tags I use as follows &lt;p&gt; for <p>.
              </jxb:javadoc>
           </jxb:class>
        </xs:appinfo>
     </xs:annotation>

     .
     .
     .
  </xs:complexType>

2) To document an element, I use the "property" tag as follows:

2）为了记录一个元素，我使用“property”标签如下：

       <xs:element name="description" type="rep:NamedString">
          <xs:annotation>
             <xs:appinfo>
                <jxb:property>
                   <jxb:javadoc>
                      &lt;p&gt;Documentation goes here.&lt;/p&gt;
                   </jxb:javadoc>
                </jxb:property>
             </xs:appinfo>
          </xs:annotation>
       </xs:element>

3) I use the same set of tags to document attributes:

3）我使用相同的标签集来记录属性：

      <xs:attribute name="name" type="xs:NCName" use="required">
          <xs:annotation>
             <xs:appinfo>
                <jxb:property>
                   <jxb:javadoc>
                      &lt;p&gt;Documentation goes here.&lt;/p&gt;
                   </jxb:javadoc>
                </jxb:property>
             </xs:appinfo>
          </xs:annotation>
       </xs:attribute>

4) To document a choice, I use the property jaxb tag, and I document the choice.

4) 为了记录一个选择，我使用了属性 jaxb 标签，并且我记录了这个选择。

    <xs:choice maxOccurs="unbounded">
          <xs:annotation>
             <xs:appinfo>
                <jxb:property>
                   <jxb:javadoc>
                      &lt;p&gt;Documentation goes here.&lt;/p&gt;
                   </jxb:javadoc>
                </jxb:property>
             </xs:appinfo>
          </xs:annotation>

          <xs:element name="value" type="rep:NamedValue" />
          <xs:element name="list" type="rep:NamedList" />
          <xs:element name="structure" type="rep:NamedStructure" />
       </xs:choice>

Attempting to document the individual choices here would fail, since this tag produces an untyped list.

尝试在此处记录各个选项将失败，因为此标记会生成一个无类型列表。

Answer 4

回答by Hubbitus

Especially for that case I wrote XJC plugin xjc-documentation-annotation-plugin.

特别是对于这种情况，我编写了 XJC 插件xjc-documentation-annotation-plugin。

What it does: `<annotation><documentation>`-> Java class annotations

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

Said we have this object described in XSD:

说我们有这个对象描述在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>

We run xjc like:

我们像这样运行 xjc：

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

And got class like (getters, setters and any annotations omitted for simplicity):

并得到了类（为了简单起见，省略了getter、setter和任何注释）：

public class CadastralBlock {
    protected String number;
}

But in my case I want known how to class and fields was named in source file!So it what this plugin do!

但在我的情况下，我想知道如何在源文件中命名和字段！这就是这个插件的作用！

So you get:

所以你得到：

@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;
}

How to use

如何使用

Manual call in commandline

在命令行中手动调用

If you want run it manually ensure jar class with plugin in run classpath and just add option -XPluginDescriptionAnnotation. F.e.:

如果您想手动运行它，请确保在运行类路径中使用插件的 jar 类，然后添加 option -XPluginDescriptionAnnotation。铁：

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

Call from Java/Groovy

从 Java/Groovy 调用

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

See test XJCPluginDescriptionAnnotationTest for example.

例如，请参见测试 XJCPluginDescriptionAnnotationTest。

Use from Gradle

从 Gradle 使用

With gradle-xjc-plugin:

使用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' ]
}

Complete gradleexample in example-project-gradledirectory of project.

项目的 example-project-gradle目录中的完整gradle示例。

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

提问by Joachim Sauer

采纳答案by Pascal Thivent

回答by skaffman

回答by John Spragge

回答by Hubbitus

What it does: `<annotation><documentation>`-> Java class annotations

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

How to use

如何使用

Manual call in commandline

在命令行中手动调用

Call from Java/Groovy

从 Java/Groovy 调用

Use from Gradle

从 Gradle 使用

相关推荐

最近更新

标签

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

提问by Joachim Sauer

采纳答案by Pascal Thivent

回答by skaffman

回答by John Spragge

回答by Hubbitus

What it does: <annotation><documentation>-> Java class annotations

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

How to use

如何使用

Manual call in commandline

在命令行中手动调用

Call from Java/Groovy

从 Java/Groovy 调用

Use from Gradle

从 Gradle 使用

相关推荐

java Java泛型强制抽象方法的返回类型

java 如何在Android的缓存目录中存储文件？

java 覆盖“equals”方法：如何确定参数的类型？

java 学习Java递归，阿克曼函数

相关推荐

最近更新

标签

What it does: `<annotation><documentation>`-> Java class annotations

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