Cómo hacer que las clases generadas contengan Javadoc a partir de la documentación de XML Schema

Question

Cómo hacer que las clases generadas contengan Javadoc a partir de la documentación de XML Schema

Actualmente estoy trabajando con un esquema XML que tiene <xsd:annotation>/<xsd:documentation> en la mayoría de los tipos y elementos. Cuando genero Java Beans a partir de este esquema XML, el Javadoc de esos Beans solo contiene información genérica generada sobre el contenido permitido del tipo/elemento.

Me gustaría ver el contenido de la etiqueta <xsd:documentation> en los lugares relevantes (por ejemplo, el contenido de esa etiqueta para un complextType debería aparecer en el Javadoc de la clase generada para representar eso complexType).

¿hay alguna manera de lograr esto?

Edit: este esquema XML se utilizará en un WSDL con JAX-WS, por lo que esta etiqueta también podría ser apropiada.

Edit 2 : He leído sobre <jxb:javadoc>. Por lo que entiendo puedo especificar que ya sea en un archivo de enlace JAXB independiente o directamente en el esquema XML. Eso casi resolvería mi problema. Pero prefiero usar la etiqueta <xsd:documentation> existente, ya que Javadoc no es el objetivo principal de la documentación (es información sobre la estructura de datos principalmente y no sobre los Java Beans generados a partir de ella) y para permitir que las herramientas que no son de JAXB también accedan a la información. Proporcionar la documentación en <jxb:javadoc> y xsd:documentation> "se siente" mal, porque estoy duplicando datos (y trabajo) sin una buena razón.

Editar 3 : Gracias a la respuesta de Pascal me di cuenta de que ya tengo la mitad de una solución: El <xsd:documentation> de complexTypes está escrito al principio de su Javadoc! El problema sigue siendo que solo que complexType s se utiliza y simpleType s (que también puede dar lugar a una clase) y los elementos siguen siendo Javadoc-less.

39

java javadoc jaxb jax-ws xjc

Author: Joachim Sauer, 2009-10-30

Source

3 answers

Esto simplemente no es posible con la implementación de referencia de JAXB. Incluso si intentara escribir un complemento XJC, descubriría que la API del complemento no tiene referencia a la definición del Esquema, por lo que no hay forma de extraer esta información.

Nuestra única esperanza es que una versión futura de JAXB arregle la situación. Hay una solicitud de característica abierta aquí.

10

Author: skaffman,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2017-06-08 22:08:38

Encuentro que las siguientes técnicas funcionan bastante bien para agregar encabezados JavaDoc a clases de elementos Java (generadas a partir de esquemas XML). Anido el JavaDoc en etiquetas definidas en el espacio de nombres jax-b, anidadas dentro de las etiquetas de anotación de esquema xml y appinfo. Nota: el espacio de nombres jaxb define tipos de etiquetas de documentación; utilizo dos de ellas: la clase y las etiquetas de propiedad. definido en el siguiente espacio de nombres: xmlns:jxb="http://java.sun.com/xml/ns/jaxb"

1) Para documentar una clase, uso un jaxb etiqueta "class" en la siguiente secuencia:

  <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) Para documentar un elemento, utilizo la etiqueta" property " de la siguiente manera:

       <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) Utilizo el mismo conjunto de etiquetas para documentar atributos:

      <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) Para documentar una elección, utilizo la propiedad etiqueta jaxb, y documento la elección.

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

Intentar documentar las opciones individuales aquí fallaría, ya que esta etiqueta produce una lista sin tipo.

4

Author: John Spragge,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2016-11-05 12:15:20

score 33 · Accepted Answer

Nunca he sido capaz de conseguir regular xsd:documentation para ser colocado en la fuente java excepto si y solo si era un Tipo Complejo. Documentación para elementos, tipos simples, etc, son ignorados.

Así que termino usando jxb:javadoc. Para ello, incluya la definición de xmlns:jxb="http://java.sun.com/xml/ns/jaxb" en su elemento <xsd:schema>.

Añadir un hijo a <xsd:complexType> o <xsd: element> o <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>

Donde XXX es "clase" o "propiedad".

Para un paquete al que le escribe un hijo 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>

La escritura de un documento HTML requiere un paréntesis con <![CDATA[ --- ]]>

(EDITAR: Mientras escribo mi respuesta, la pregunta ha sido editada por el OP, así que la estoy actualizando en consecuencia)

En mi caso, javadoc era el único objetivo por lo que era aceptable usar jxb:javadoc. Pero tu actualización tiene mucho sentido y, en realidad, estoy totalmente de acuerdo contigo. Lamentablemente, nunca encontré una solución ideal para la situación que describes (así que seguiré esta pregunta con mucho cuidado). Tal vez usted podría utilizar algo así como xframe para generar documentación desde xsd:documentation, pero esto no responde a la pregunta.