45

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

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

有什么办法可以做到这一点？

编辑：这个 XML Schema 将在带有 JAX-WS 的 WSDL 中使用，所以这个标签也可能是合适的。

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

编辑 3：感谢 Pascal 的回答，我意识到我已经有了一半的解决方案：<xsd:documentation>scomplexType被写入其 Javadoc 的开头！问题仍然是只使用了complexTypes 并且simpleTypes（也可以导致类）和元素仍然是 Javadoc-less。

4

4 回答 4

38

除非且仅当它是复杂类型，否则我永远无法将常规xsd:documentation放置在 java 源代码中。元素、简单类型等的文档将被忽略。

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

将孩子添加到<xsd:complexType>or<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，但这并不能回答问题。

于 2009-10-30T17:15:18.180 回答
13

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

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

于 2009-11-02T09:51:31.027 回答
5

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

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

  <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）为了记录一个元素，我使用“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）我使用相同的标签集来记录属性：

      <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）为了记录选择，我使用属性 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>

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

于 2016-11-05T12:15:20.520 回答
0

特别是对于那种情况，我编写了 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

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

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。铁：

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

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

于 2019-01-28T01:30:07.443 回答