Comment faire en sorte que les classes générées contiennent Javadoc à partir de la documentation XML Schema

https://stackoverflow.com/questions/1650249

22-07-2019
|

Question

Je travaille actuellement avec un schéma XML qui a <xsd:annotation> / <xsd:documentation> sur la plupart des types et des éléments. Lorsque je génère des Java Beans à partir de ce schéma XML, la Javadoc de ces Beans contient uniquement des informations génériques sur le contenu autorisé du type / élément.

J'aimerais voir le contenu de la balise <jxb:javadoc> aux endroits appropriés (par exemple, le contenu de cette balise pour un type complexe doit apparaître dans le Javadoc de la classe générée pour représenter ce type complexe).

Y a-t-il un moyen d'y parvenir?

Modifier : ce schéma XML sera utilisé dans un WSDL avec JAX-WS. Cette balise pourrait donc également convenir.

Modifier 2 : j'ai lu des articles sur xsd:documentation>. D'après ce que j'ai compris, je peux le spécifier dans un fichier de liaison JAXB séparé ou directement dans le schéma XML. Cela résoudrait presque mon problème. Mais je préférerais utiliser la balise complexType existante, Javadoc n'étant pas la cible principale de la documentation (ce sont des informations sur la structure de données principalement et non sur les beans Java générés à partir de celle-ci) et d'autoriser l'accès à des outils non JAXB. l'information aussi. Fournir la documentation à la fois dans simpleType et dans <=> & Quot; & Quot; faux, parce que je duplique des données (et du travail) sans raison valable.

Éditer 3 : grâce à la réponse de Pascal, j'ai compris que j'avais déjà une demi-solution: le <=> de <=> s est écrit au début de son Javadoc! Le problème est toujours seulement que <=> s est utilisé et <=> s (ce qui peut également donner lieu à une classe) et que les éléments sont toujours sans javadoc.

La solution

Je n'ai jamais réussi à obtenir des xsd:documentation sources régulières dans le code source Java, sauf si et seulement si il s'agissait d'un type complexe. Documentation pour éléments, types simples, etc sont ignorés.

Donc, je finis par utiliser jxb:javadoc. Pour ce faire, incluez la définition de xmlns: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>:

<xsd:annotation><xsd:appinfo><jxb:XXX><jxb:javadoc>
  This is my comment for a class/property
</jxb:javadoc></jxb:XXX></xsd:appinfo></xsd:annotation>

Où XXX est " classe " ou " propriété ".

Pour un package, vous écrivez un enfant sur 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>

L'écriture d'un document HTML nécessite un encadrement avec <![CDATA[ --- ]]>

(EDIT: lors de la rédaction de ma réponse, la question a été modifiée par le PO, je la mets à jour en conséquence)

Dans mon cas, javadoc étant la seule cible, il était acceptable d’utiliser <=>. Mais votre mise à jour est parfaitement logique et, en fait, je suis tout à fait d’accord avec vous. Malheureusement, je n'ai jamais trouvé de solution idéale à la situation que vous décrivez (je vais donc suivre cette question très attentivement). Vous pourriez peut-être utiliser quelque chose comme xframe pour générer de la documentation à partir de <=>, mais cela ne ' t répondre à la question.

Autres conseils

Cela n’est tout simplement pas possible avec l’implémentation de référence JAXB. Même si vous essayiez d'écrire un plugin XJC, vous constateriez que l'API du plugin ne fait pas référence à la définition de schéma, il n'y a donc aucun moyen d'extraire cette information.

Notre seul espoir est qu'une future version de JAXB corrige la situation. Il existe une demande de fonctionnalité ouverte ici .

Je trouve que les techniques suivantes fonctionnent assez bien pour ajouter des en-têtes JavaDoc aux classes d'éléments Java (générées à partir de schémas XML). J'imbrique le JavaDoc dans les balises définies dans l'espace de noms jax-b, imbriquées dans l'annotation de schéma xml et les balises appinfo. Notez que l’espace de noms jaxb définit les types de balises de documentation; J'utilise deux d'entre eux: la classe et les balises de propriété. défini dans l'espace de noms suivant: xmlns: jxb = " http: //java.sun.com/xml/ns/jaxb "

1) Pour documenter une classe, j'utilise un jaxb " class " balise dans la séquence suivante:

  <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) Pour documenter un élément, j'utilise la " propriété " tag comme suit:

       <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) J'utilise le même ensemble de balises pour documenter les attributs:

      <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) Pour documenter un choix, j'utilise la propriété tag jaxb et je documente le choix.

    <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>

Tenter de documenter les choix individuels ici échouerait, car cette balise produit une liste non typée.

Surtout dans ce cas, j’ai écrit le plug-in XJC xjc-documentation-annotation-plugin .

Ce que ça fait: `<annotation><documentation>` - > Annotations de classe Java

Nous avons cet objet décrit dans 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>

Nous exécutons xjc comme:

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

Et vous avez la classe comme (getters, setters et toutes les annotations omises pour plus de simplicité):

public class CadastralBlock {
    protected String number;
}

Mais dans mon cas, je veux savoir comment classer et les champs ont été nommés dans le fichier source! Voilà donc ce que ce plugin fait!

Vous obtenez donc:

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

Comment utiliser

Appel manuel en ligne de commande

Si vous souhaitez l'exécuter manuellement, assurez-vous que la classe jar avec le plug-in est exécutée dans classpath et ajoutez simplement l'option -XPluginDescriptionAnnotation. F.e.:

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

Appeler depuis Java / Groovy

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

Voir le test XJCPluginDescriptionAnnotationTest par exemple.

Utiliser à partir de Gradle

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

Complétez gradle l'exemple dans exemple -project-gradle répertoire du projet.

Licencié sous: CC-BY-SA avec attribution

Non affilié à StackOverflow