如何使生成的类包含的Javadoc从XML架构文档
题
我目前使用具有对大多数类型和元素<xsd:annotation>
/ <xsd:documentation>
一个XML Schema工作。当我生成从该XML模式的Java豆,那么这些豆的Javadoc仅包含关于类型/元件的允许的内容一些通用生成的信息。
我想看到<xsd:documentation>
标签中的相关位置(该标签的一个complextType含量应该在产生表示的complexType类的Javadoc显示例如)的含量。
有什么办法来实现这一目标?
修改强>:这个XML模式将与JAX-WS一个WSDL使用,所以该标签可能是适当的,以及
修改2 强>:我读过有关<jxb:javadoc>
。据我了解,我可以指定,要么在一个单独的JAXB绑定文件或直接在XML Schema。这几乎可以解决我的问题。但我宁愿使用现有的<xsd:documentation>
标签,因为Javadoc中是不是文档的主要目标(这是关于数据结构的信息主要是和不是从它生成的Java Bean)的,并允许非JAXB工具来访问信息为好。提供了两个<jxb:javadoc>
和xsd:documentation>
的文档“感觉”不对,因为我没有很好的理由复制数据(工作)。
修改3 :多亏了帕斯卡的答案,我意识到,我已经有一半的解决方案:<xsd:documentation>
s的complexType
写入其的Javadoc的开始!问题仍然是仅该complexType
s被使用和simpleType
s(这也可导致在一个类)和元素仍然Javadoc的更小。
解决方案
我从来没有能够得到定期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
文档,但是这并没有回答的问题。
其他提示
这恰恰是不可能的JAXB参考实现。即使你尝试写一个XJC插件,你会发现该插件API没有给出参考架构定义,所以没有办法来提取这些信息。
我们唯一的希望是,JAXB的未来版本中修复的情况。此处有一个开放功能请求。
我发现以下的技术工作得很好,用于将报头的JavaDoc到Java元素类(从XML模式生成)。我窝的JavaDoc在JAX-B命名空间中定义的标签,嵌套在XML模式注释和AppInfo标签内。注意JAXB命名空间定义类型的文档标签;我用两个有:类和属性标记。的xmlns:在以下的命名空间中定义JXB = “http://java.sun.com/xml/ns/jaxb”
1)文件A类,我使用在下面序列的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 <p> for <p>.
</jxb:javadoc>
</jxb:class>
</xs:appinfo>
</xs:annotation>
.
.
.
</xs:complexType>
2)为了记录一个元素,我使用“属性”标记,如下所示:
<xs:element name="description" type="rep:NamedString">
<xs:annotation>
<xs:appinfo>
<jxb:property>
<jxb:javadoc>
<p>Documentation goes here.</p>
</jxb:javadoc>
</jxb:property>
</xs:appinfo>
</xs:annotation>
</xs:element>
3)I使用同一组的标记来记录属性:
<xs:attribute name="name" type="xs:NCName" use="required">
<xs:annotation>
<xs:appinfo>
<jxb:property>
<jxb:javadoc>
<p>Documentation goes here.</p>
</jxb:javadoc>
</jxb:property>
</xs:appinfo>
</xs:annotation>
</xs:attribute>
4)为了证明选择的,我使用属性JAXB标签,并予记录的选择。
<xs:choice maxOccurs="unbounded">
<xs:annotation>
<xs:appinfo>
<jxb:property>
<jxb:javadoc>
<p>Documentation goes here.</p>
</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>
试图在这里记录了个人的选择会失败,因为这个标签 产生一个无类型列表。
特别是对于这种情况下我写XJC插件 XJC的文档的注释-插件一>
作用:<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
和GOT类等(吸气剂,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;
}
如何使用
在命令行手动调用
如果你想运行它手动确保罐子类插件在运行类路径和只添加选项-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这个-XJC-插件:
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' ]
}