The @WSDLDocumentation annotation is defined by the
org.apache.cxf.annotations.WSDLDocumentation interface.
It can be placed on the SEI or the SEI methods.
This annotation enables you to add documentation, which will then appear within
wsdl:documentation elements after the SEI is converted to
WSDL. By default, the documentation elements appear inside the port type, but you
can specify the placement property to make the documentation appear at other locations
in the WSDL file. Table 1.9 shows the
properties supported by the @WSDLDocumentation
annotation.
Table 1.9. @WSDLDocumentation properties
| Property | Description |
|---|---|
value | (Required) A string containing the documentation text. |
placement | (Optional) Specifies where in the WSDL file this documentation is to appear. For the list of possible placement values, see Placement in the WSDL contract. |
faultClass | (Optional) If the placement is set to be
FAULT_MESSAGE, PORT_TYPE_OPERATION_FAULT, or
BINDING_OPERATION_FAULT, you must also set this property to the Java
class that represents the fault. |
The @WSDLDocumentationCollection annotation is defined
by the
org.apache.cxf.annotations.WSDLDocumentationCollection
interface. It can be placed on the SEI or the SEI methods.
This annotation is used to insert multiple documentation elements at a single placement location or at various placement locations.
To specify where the documentation should appear in the WSDL contract, you can specify
the placement property, which is of type
WSDLDocumentation.Placement. The placement can have one of the following
values:
WSDLDocumentation.Placement.BINDINGWSDLDocumentation.Placement.BINDING_OPERATIONWSDLDocumentation.Placement.BINDING_OPERATION_FAULTWSDLDocumentation.Placement.BINDING_OPERATION_INPUTWSDLDocumentation.Placement.BINDING_OPERATION_OUTPUTWSDLDocumentation.Placement.DEFAULTWSDLDocumentation.Placement.FAULT_MESSAGEWSDLDocumentation.Placement.INPUT_MESSAGEWSDLDocumentation.Placement.OUTPUT_MESSAGEWSDLDocumentation.Placement.PORT_TYPEWSDLDocumentation.Placement.PORT_TYPE_OPERATIONWSDLDocumentation.Placement.PORT_TYPE_OPERATION_FAULTWSDLDocumentation.Placement.PORT_TYPE_OPERATION_INPUTWSDLDocumentation.Placement.PORT_TYPE_OPERATION_OUTPUTWSDLDocumentation.Placement.SERVICEWSDLDocumentation.Placement.SERVICE_PORTWSDLDocumentation.Placement.TOP
Example 1.8 shows how to add a
@WSDLDocumentation annotation to the SEI and to
one of its methods.
Example 1.8. Using @WSDLDocumentation
@WebService @WSDLDocumentation("A very simple example of an SEI") public interface HelloWorld { @WSDLDocumentation("A traditional form of greeting") String sayHi(@WebParam(name = "text") String text); }
When WSDL, shown in Example 1.9, is generated from the
SEI in Example 1.8, the default placements of the
documentation elements are, respectively,
PORT_TYPE and PORT_TYPE_OPERATION.
Example 1.9. WSDL generated with documentation
<wsdl:definitions ... > ... <wsdl:portType name="HelloWorld"> <wsdl:documentation>A very simple example of an SEI</wsdl:documentation> <wsdl:operation name="sayHi"> <wsdl:documentation>A traditional form of greeting</wsdl:documentation> <wsdl:input name="sayHi" message="tns:sayHi"> </wsdl:input> <wsdl:output name="sayHiResponse" message="tns:sayHiResponse"> </wsdl:output> </wsdl:operation> </wsdl:portType> ... </wsdl:definitions>
Example 1.10 shows how to add a
@WSDLDocumentationCollection annotation to an SEI.
Example 1.10. Using @WSDLDocumentationCollection
@WebService @WSDLDocumentationCollection( { @WSDLDocumentation("A very simple example of an SEI"), @WSDLDocumentation(value = "My top level documentation", placement = WSDLDocumentation.Placement.TOP), @WSDLDocumentation(value = "Binding documentation", placement = WSDLDocumentation.Placement.BINDING) } ) public interface HelloWorld { @WSDLDocumentation("A traditional form of Geeky greeting") String sayHi(@WebParam(name = "text") String text); }
 |  |  |
 |
