Comment faire des classes générées contiennent Javadoc de Schéma XML de la documentation
Je suis actuellement en train de travailler avec un Schéma XML qui a <xsd:annotation>
/<xsd:documentation>
sur la plupart des types et des éléments. Lorsque je créer des Beans Java à partir de ce Schéma XML, puis la Javadoc de ces grains ne contient que quelques génériques généré des informations sur les permis de contenu du type d'élément.
J'aimerais voir le contenu de la <xsd:documentation>
balise dans certains endroits (par exemple le contenu de cette balise pour un complextType doit s'afficher dans la Javadoc de la classe générée à représenter la complexType).
Est-il un moyen pour y parvenir?
Modifier: ce Schéma XML sera utilisé dans un document WSDL avec JAX-WS, de sorte que cette balise peut être approprié ainsi.
Edit 2: j'ai lu sur <jxb:javadoc>
. À partir de ce que je comprends, je peux préciser que, soit dans un autre JAXB de liaison de fichier ou directement dans le Schéma XML. Qui serait presque à résoudre mon problème. Mais je préfère utiliser le <xsd:documentation>
tag, depuis Javadoc n'est pas la principale cible de la documentation (c'est l'information à propos de la structure de données principalement et non sur les Java Beans généré à partir d'elle) et pour permettre aux non-JAXB outils d'accès à l'information. Fournir de la documentation dans les deux <jxb:javadoc>
et xsd:documentation>
"sent" mal, parce que je suis duplication des données (et de travail) pour aucune bonne raison.
Modifier 3: Merci pour la réponse par Pascal, j'ai réalisé que j'ai déjà une demi-solution: La <xsd:documentation>
de complexType
s est écrit au début de sa Javadoc! Le problème est encore que seulement que complexType
s est utilisé et simpleType
s (ce qui peut également entraîner dans une classe) et les éléments qui sont encore Javadoc-moins.
- Est l'aide de <jxb:javadoc> une option?
- merci, j'ai répondu que, dans la question.
Vous devez vous connecter pour publier un commentaire.
Je n'ai jamais été en mesure d'obtenir régulièrement des
xsd:documentation
être placé dans le source java à l'exception si et seulement si c'était un Type Complexe. Documentation pour les éléments, les types simples,etc sont ignorés.
Donc, j'ai fini par utiliser
jxb:javadoc
. Pour ce faire, inclure la définition de laxmlns:jxb="http://java.sun.com/xml/ns/jaxb"
dans votre<xsd:schema>
élément.Ajouter un enfant à
<xsd:complexType>
ou<xsd: element>
ou<xsd:attribute>
:Où XXX est soit "classe" ou de "propriété".
Pour un package de vous écrire à un enfant de
xsd:schema
L'écriture de code HTML document nécessite bracketing avec
<![CDATA[ --- ]]>
(EDIT: lors de l'écriture de ma réponse, la question a été modifié par l'OP donc je suis à jour en conséquence)
Dans mon cas, javadoc était la seule cible de sorte qu'il est acceptable d'utiliser
jxb:javadoc
. Mais votre mise à jour a du sens et, en fait, je suis totalement d'accord avec vous. Malheureusement, je n'ai jamais trouvé une solution idéale pour la situation que vous décrivez (donc je vais suivre cette question avec beaucoup de précaution). Peut-être que vous pouvez utiliser quelque chose comme xframe pour générer la documentation dexsd:documentation
, mais cela ne veut pas répondre à la question.complexType
s obtenir la Javadoc. C'est un petit pas de plus vers ce que j'aime, mais pas encore parfait.Ce n'est tout simplement pas possible avec des JAXB l'implémentation de référence. Même si vous essayez d'écrire un XJC plugin, vous trouveriez que l'API de plugin est donné aucune référence à la définition de Schéma, donc il n'y a aucun moyen d'extraire cette information.
Notre seul espoir est qu'une version future de JAXB corrige la situation. Il y a un la fonction open demande ici.
:-(
javaee/jaxb-v2
est une version archivée sur le repo et il n'y a pas de problèmes d'onglet; le nouveau repo est à eclipse-ee4j/jaxb-ri et les questions connexes sont #273 et #460 et- Je trouver les techniques qui fonctionnent assez bien pour l'ajout de JavaDoc en-têtes de Java classes d'éléments (généré à partir de schémas XML). Je nest la JavaDoc dans les balises définies dans le jax-b espace de noms, imbriqué dans le xml schéma d'annotation et de appinfo balises. Remarque le jaxb espace de noms définit les types de documentation sur les tags; j'utilise deux de là: la classe et les balises de propriété. définie dans l'espace de noms suivant: xmlns:jxb="http://java.sun.com/xml/ns/jaxb"
1) Pour la documentation d'une classe, j'utilise un jaxb "classe" de la balise dans la séquence suivante:
2) un élément, j'utilise la "propriété" de la balise comme suit:
3) - je utiliser le même ensemble de balises pour les attributs des documents:
4) du document À un choix, j'utilise la propriété jaxb tag, et j'document le choix.
Tenter de document de la personne de choix ici serait un échec, puisque cette balise
produit une liste non typée.
En particulier pour les cas que j'ai écrit XJC plugin xjc-documentation-annotation-plugin.
Ce qu'il fait:
<annotation><documentation>
-> Java de la classe d'annotationsDit que nous avons cet objet décrit dans
XSD
:Nous courons xjc comme:
Et a obtenu la classe comme (getters, setters et les annotations omis pour plus de simplicité):
Mais dans mon cas, je veux savoir comment la classe et des champs a été nommé dans le fichier source! Donc ce que ce plugin ne!
De sorte que vous obtenez:
Comment utiliser
Manuel de l'appel en ligne de commande
Si vous voulez l'exécuter manuellement assurer pot de classe avec le plugin dans l'exécution classpath et ajoutez simplement l'option
-XPluginDescriptionAnnotation
. F. e.:Appel de Java/Groovy
Voir test XJCPluginDescriptionAnnotationTest par exemple.
Utilisation de Gradle
Avec gradle-xjc-plugin:
Complète
gradle
exemple dans exemple de projet gradle répertoire de projet.