THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
Xml
...
| Span | ||
|---|---|---|
| ||
| JAX-RS Services Description |
...
...
| Table of Contents |
|---|
Swagger
Swagger-First Development
...
Please see the Swagger2Feature page for more information
WADL
CXF JAX-RS supports (Web Application Description Language|http://www.w3.org/Submission/wadl] (WADL).
Users can use WADL documents to generate the initial code and have WADL auto-generated on demand.
...
| No Format |
|---|
wadl2java -p <package-name> -sp <[schema-namespace =]package-name>*
-tMap <schema-type = java-type>* -repMap <media-type = java-type>*
-resource <resource-name> -b <binding-file-name>* -catalog <catalog-file-name>
-d <output-directory> -compile -classdir <compile-classes-directory> -interface -impl
-noTypes -inheritResourceParams -generateEnums -supportMultipleXmlReps -javaDocs
-generateResponseIfHeadersSet -generateResponseForMethods<methodNames>* -async<methodNames>* -xjc<xjc-arguments>*
-rx <library> -authentication <name:password> -validate -h -v -verbose -quiet <wadl>
|
...
'generateResponseForMethods' and 'generateResponseIfHeadersSet' - from 2.7.12/3.0.0, 'validate' - from 2.7.13/3.2.0/3.1.0, 'javaDocs' - from 3.1.4, 'authentication' - from 3.1.14/3.2.1, 'rx' - from 3.2.13/3.3.6.
The options are reviewed in the following table.
Option | Interpretation |
|---|---|
| Displays the online help for this utility and exits. |
| Specifies the package name of root resource classes |
| Specifies one or more package names corresponding to individual schema namespaces |
| Specifies a full name of root resource class if WADL contains a single resource |
| Default option unless -impl option is used - Java interfaces with JAX-RS annotations are generated |
| Generates starting implementation code. Can also be used with -interface option |
| Requests that no schema generation is needed. Can also be used with -tMap option |
| Provides mapping between schema elements and java types |
| Provides mapping between media types and java types |
| Specifies JAXB binding files. Use multiple -b flags to specify multiple entries. |
| Specifies catalog file to map referenced wadl/schemas |
| Specifies the directory into which the generated code files are written. |
| Compiles generated Java files. |
| Specifies the directory into which the compiled class files are written. |
| Generate JAX-RS Response instead of 'void' for methods with no response representations. |
| Get current resource-level path or matrix parameters added to generated methods for all descendant resources. |
| Generates Java enums for parameters with options. |
| Generates separate method for every XML representation in a single WADL request element. |
| -javaDocs | Converts WADL doc elements into JavaDocs |
| -generateResponseIfHeadersSet | Generates JAX-RS Response method response type if WADL response element for a given method has 'header' parameters |
| -generateResponseForMethods methodNames | Generates JAX-RS Response method response type, methodNames is a comma-separated list of WADL method name or id attributes |
| Adds JAX-RS 2.0 AsyncResponse parameter to generated methods, methodNames is a comma-separated list of WADL method name or id attributes |
| -authentication | Specifies a colon separated user name and password for retrieving the remote WADL content from the servers requiring the authentication |
| Specifies a comma separated list of arguments that are passed directly to the XJC processor, example -xjc-Xts. |
-rx <library> | Specifies the use of the JAX-RS 2.1 reactive extensions for generating method signatures. The supported <library> values are:
|
| -validate | Validate a WADL document against the WADL schema |
wadlurl | The path and name of the WADL file to use in generating the code. |
...
In some cases, example when describing JSON arrays, you may want to have an explicit collection of types defined in schema generated. In this case use -tMap or -repMap option with a value such as "List..MyType".
The reactive extensions support is limited to Java 8 standard library APIs only, which essentially means CompletionStage / CompletableFuture are supported at the moment. Please note that the void / one-way methods are not generated with CompletionStage / CompletableFuture and kept unchanged.
JAXB customizations
At the moment it is possible to apply external JAXB customizations to WADL grammars however it is not possible yet to restrict a given customization to a specific WADL document or explicitly inlined schema. Linking binding to external schemas works, for example, the following bindings file can be used:
...
WADL documents can include doc fragments.
Users may want to use Description annotations which can be attached to resource classes and methods.
Note that starting from CXF 2.4.0, Description annotations can be applied to input parameters. Additionally, a method-level Descriptions annotation can have a collection of categorized Description annotations, with each Description targeting a specific WADL element by setting its 'target' property to one of the DocTarget values. For example, one can use a Descriptions annotation to document the response representation of a particular resource method, as well as add documentation fragments to WADL wadl:method/wadl:request and wadl:method/wadl:response elements:
...
- applicationTitle: can be used to create an application title.
- namespacePrefix: defaut is 'prefix', it can be set to other value such as 'ns'.
- ignoreForwardSlash: can be used to enforce that resource path values do not start from '/'
- addResourceAndMethodIds: WadlGenerator will add "id" attributes to wadl:resource and wadl:method elements
An ElementClass annotation can help with representing JAX-RS Response elements in the generated WADL.
...
If no JAXB is used then you can attach an XMLName annotation to method input or output types. Alternatively, you can register an instance of ElementQNameResolver with the WadlGenerator which will be used for creating wadl:representation/@element values.
...
Starting from CXF 2.6.2 it is possible to affect the base address specified in the auto-generated WADL (in wadl:resources/@base attribute).
WADLGenerator can be indirectly configured by setting a jaxrs:server/@publishedEndpointUrl attribute, similarly to the way CXF WSDL generator can be configured by setting a jaxws:endpoint/@publishedEndpointUrl attribute.
java2wadl Maven plugin
CXF 3.0.0 and 2.7.11 introduce java2wadl plugin for generating WADL at the build time:
...