Как заставить сгенерированные классы содержать Javadoc из документации XML-схемы
https://stackoverflow.com/questions/1650249
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
RussianВопрос
В настоящее время я работаю со схемой XML, которая имеет <xsd:annotation> / <xsd:documentation> для большинства типов и элементов. Когда я генерирую Java Beans из этой XML-схемы, Javadoc этих Beans содержит только некоторую общую сгенерированную информацию о разрешенном содержимом типа / элемента.
Я хотел бы видеть содержимое тега <jxb:javadoc> в соответствующих местах (например, содержимое этого тега для completextype должно отображаться в Javadoc класса, сгенерированного для представления этого complexType).
Есть ли способ добиться этого?
Изменить : эта XML-схема будет использоваться в WSDL с JAX-WS, поэтому этот тег также может быть подходящим.
Изменить 2 . Я читал о xsd:documentation>. Из того, что я понимаю, я могу указать это либо в отдельном файле привязки JAXB, либо непосредственно в схеме XML. Это почти решило бы мою проблему. Но я бы предпочел использовать существующий тег complexType, так как Javadoc не является основной целью документации (это прежде всего информация о структуре данных, а не о сгенерированных из нее Java-компонентах) и позволяет инструментам, не являющимся JAXB, получать доступ информация также. Предоставление документации в simpleType и <=> & Quot; чувствует себя & Quot; неправильно, потому что я дублирую данные (и работаю) без уважительной причины.
Изменить 3 . Благодаря ответу Паскаля я понял, что у меня уже есть половина решения: <=> из <=> записано в начале его Javadoc! Проблема по-прежнему заключается в том, что only , что <=> s используется и <=> 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 - это либо " class " или " свойство ".
Для пакета вы пишете дочерний элемент в 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[ --- ]]>
(РЕДАКТИРОВАТЬ: во время написания моего ответа ОП редактировал вопрос, поэтому я соответствующим образом обновляю его)
В моем случае единственной целью был javadoc, поэтому его можно было использовать <=>. Но ваше обновление имеет смысл, и, на самом деле, я полностью согласен с вами. К сожалению, я никогда не находил идеального решения для ситуации, которую вы описываете (поэтому я буду очень внимательно следить за этим вопросом). Возможно, вы могли бы использовать что-то вроде xframe для создания документации из <=>, но это не так не отвечу на вопрос.
Другие советы
Это просто невозможно с эталонной реализацией JAXB. Даже если вы попытаетесь написать плагин XJC, вы обнаружите, что API плагина не имеет ссылки на определение схемы, поэтому нет способа извлечь эту информацию.
Мы надеемся, что будущая версия JAXB исправит ситуацию. есть запрос на открытие функции здесь .
Я считаю, что следующие методы очень хорошо работают для добавления заголовков JavaDoc в классы элементов Java (сгенерированные из схем XML). Я вкладываю JavaDoc в теги, определенные в пространстве имен jax-b, вложенные в аннотацию схемы xml и теги appinfo. Обратите внимание, что пространство имен jaxb определяет типы тегов документации; Я использую два из них: класс и теги свойств. определяется в следующем пространстве имен: xmlns: jxb = " http: //java.sun.com/xml/ns/jaxb "
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 <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) Я использую тот же набор тегов для атрибутов документа:
<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-documents-annotation-plugin .
Сказали, что этот объект описан в Мы запускаем xjc как: И получил класс как (геттеры, сеттеры и любые аннотации опущены для простоты): Но в моем случае я хочу знать, как класс и поля были названы в исходном файле! Так что же делает этот плагин! Итак, вы получите: Если вы хотите запустить его вручную, обеспечьте jar-класс с плагином в run classpath и просто добавьте параметр См., например, тестовый XJCPluginDescriptionAnnotationTest. Выполните Что он делает:
<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 -npa -no-header -d src/main/generated-java/ -p xsd.generated scheme.xsd
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() {...}
)
Использование из Gradle
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 пример в примере -project-gradle каталог проекта.
