Any way to generate WSDL documentation from Javadoc with JAX-WS?

Question

I'm hoping that an extension of some kind is available that does this (although I suppose that my hope is foolishly optimistic).

   /**
     * <p>
     * Gets the {@link ResultObject} given the identifier. The following
     * fields are not available for some users and will contain a null value:
     * </p>
     * 
     * <ul>
     * <li>{@code resultObject.comment}</li>
     * <li>{@code resultObject.anotherObject.actionById}</li>
     * <li>{@code resultObject.anotherObject.actionByName}</li>
     * </ul>
     * 
     * <p>
     * The {@code daysInPurgatory} value will be {@code -1} when not
     * applicable
     * </p>
     * 
     * @param requestUser
     *            the user initiating the request
     * @param identifier
     *            the id of the ResultObject
     * @return the {@link ResultObject} or {@code null} if none exists
     * @throws SomeException
     *             if the {@code identifier} is {@code null}
     */
    @WebMethod
    @WebResult(name = "resultObject")
    public ResultObject getResultObjectById(
     @WebParam(name = "RequestUser", header = true, partName = "RequestUser") final String requestUser,
     @WebParam(name = "identifier") final Long identifier)
     throws SomeException;

Thanks, LES2

Answer 1

You may look at Enunciate. It's possible to use it's Maven plugin to generate static HTML files from Javadoc comments. This works for SOAP (i.e. JAX-WS) and REST (i.e. JAX-RS) endpoints.

Interesting reads:

• https://github.com/stoicflame/enunciate/wiki/Documentation-Only
• http://raibledesigns.com/rd/entry/my_experience_with_java_rest

Production Examples:

• http://www.realtybaron.com/api/
• http://www.agentrank.com/api/
• http://api.setlist.fm/docs/index.html

Answer 2

You're not the only one looking for a way to generate WSDL documentation (see the Generating WSDL documentation from Javadoc thread) but, AFAIK, there is no standard JAX-WS way for doing this.

Now, maybe have a look at JBoss proprietary annotation @Documentation mentioned in JBWS-1850 that generates jaxws:binding artifacts described in section 2.9 Javadoc Customization when using Java->WSDL approach as well. It's not exactly what you asked for but it might give you some ideas.

In any case, I guess that this would require providing your own WSDLGeneratorExtension to extend wsgen and generate the desired WSDL.

Answer 3

In one project we published a lot of WSDLs. For every Web Service we have exposed a WS method "getDocumentationURL()". This method deliver back a link to the JavaDoc generated from the SEI. The JavaDoc was place on a accessible intranet server.