Enunciate Specific Annotations

Note: The following applies to Enunciate version 2. For information about enunciate-specific annotations in Enunciate 1.x, see Enunciate Specific Annotations (Version 1)

Enunciate-Specific Annotations

This document serves as a reference for the set of Enunciate-specific annotations that can be used to enhance the documentation for your Web service API.

All annotations are contained within the com.webcohesion.enunciate.metadata package, which has been abbreviated to c.w.e.m below for readability purposes.

All annotations are contained in the enunciate-core-annotations.jar (Maven coordinates: com.webcohesion.enunciate:enunciate-core-annotations).

Enhancements to JAX-RS

c.w.e.m.rs.StatusCodes

Applied to a resource class or a resource method. Used to document the set of status codes that may be responses to the operation. The status codes annotated on a method are appended to the status codes annotated on the defining resource class.

Example:

@GET
@Path("person/{id}")
@StatusCodes ({
  @ResponseCode ( code = 404, condition = "The person is not found.")
})
Person readPerson(@PathParam("id") String id);

c.w.e.m.rs.Warnings

Applied to a resource class or a resource method. Used to document the set of warning headers that may be included upon invocation of the operation. The warnings annotated on a method are appended to the warnings annotated on the defining resource class.

Example:

@GET
@Path("person/{id}")
@Warnings ({
  @ResponseCode ( code = 299, condition = "The reason the person wasn't found, if applicable.")
})
Person readPerson(@PathParam("id") String id);

c.w.e.m.rs.TypeHint

Applied to a resource method. Some JAX-RS methods may return e.g. javax.ws.rs.core.Response and Enunciate can't tell what kind of a response is expected in the response body. The TypeHint annotation is used to give Enunciate a hint about what is to be returned.

Example:

@GET
@Path("person/{id}")
@TypeHint (Person.class)
Person readPerson(@PathParam("id") String id);

@GET
@Path("persons")
@TypeHint (Person[].class)
Person readPersons(@QueryParam("id") String[] ids);

c.w.e.m.rs.ResponseHeaders

Applied to a resource class or a resource method. Used to document the set of response headers that may be included upon invocation of the operation. The response headers annotated on a method are appended to the warnings annotated on the defining resource class.

Example:

@POST
@ResponseHeaders (
  @ResponseHeader( name = "Location", description = "The location of the created person.")
)
Person createPerson(Person person);

Enhancements for Documentation

c.w.e.m.Label

Applied to a resource class, a data type, a web fault or a web service. Used to customize the label that is used for the element in the generated documentation.

Example:

@Label ("PersonRelativeAge")
enum Age {

  old,

  young

}

c.w.e.m.DocumentationExample

Applied to a data type accessor (field or property). Used to suggest an example value for XML/JSON examples.

Example:

class Person {

  @DocumentationExample("male")
  public String gender;

}

c.w.e.m.rs.ResourceGroup

Applied to a resource class or a resource method. Used to customize how resources are grouped in the documentation. See Module-JAXRS.

Example:

@Path("/persons")
@ResourceGroup("Person API")
class PersonResource {

}

c.w.e.m.rs.ResourceLabel

Applied to a resource class or a resource method. Used to customize how resources or resource methods are labeled in the generated documentation.

Example:

@Path("/persons")
@ResourceLabel("Person Resource")
class PersonResource {

}

Processor Directives

c.w.e.m.Ignore

Applied to a Java class. Used to suggest to Enunciate that the annotated class should be ignored, if possible. The class may not be able to be ignored if it's explicitly referenced from a service, resource, or data type that is not excluded.

Example:

@Ignore
class PersonUtils {

}