Skip to content

Enunciate Specific Annotations

Jump to bottom Edit New page
Ryan Heaton edited this page Apr 24, 2020 · 31 revisions

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 and JavaDoc Tags

This document serves as a reference for the set of Enunciate-specific annotations and JavaDoc tags 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 REST API

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

@ResponseCode optionally takes a type property to associate a specific response object with this code. (Example: type=@TypeHint(ErrorResponse.class))

@HTTP JavaDoc Tag

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. Originally defined by jax-doclets.

Example:
/**
 * @HTTP 404 If the person is not found.
 */
@GET
@Path("person/{id}")
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);

@HTTPWarning JavaDoc Tag

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:
/**
 * @HTTPWarning 299 The reason the person wasn't found, if applicable.
 */
@GET
@Path("person/{id}")
Person readPerson(@PathParam("id") String id);

c.w.e.m.rs.TypeHint

Applied to a resource method or resource parameter. Enunciate might not be able to determine the structure of the request and/or response body from the method signature. (For example, some JAX-RS methods may return javax.ws.rs.core.Response.) The TypeHint annotation is used to give Enunciate a hint about what is to be returned or consumed.

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

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

@POST
@Path("person/{id}")
Person updatePerson(@TypeHint(Person.class) InputStream data);

@returnWrapped JavaDoc Tag

Applied to a resource method. Enunciate might not be able to determine the structure of the response body from the method signature. (For example, some JAX-RS methods may return javax.ws.rs.core.Response.) The @returnWrapped JavaDoc tag is used to give Enunciate a hint about what is to be returned. Originally defined by jax-doclets.

Example:
/**
 * @returnWrapped com.mycompany.Person
 */
@GET
@Path("person/{id}")
Person readPerson(@PathParam("id") String id);

@inputWrapped JavaDoc Tag

Applied to a resource method. Enunciate might not be able to determine the structure of the request body from the method signature. The @inputWrapped JavaDoc tag is used to give Enunciate a hint about what is to be consumed. Originally defined by jax-doclets.

Example:
/**
 * @inputWrapped com.mycompany.Person
 */
@POST
@Path("person/{id}")
Person updatePerson(InputStream data);

c.w.e.m.rs.RequestHeaders

(Since Enunciate 2.3)

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

The @RequestHeaders annotation was provided as a way to document request headers that aren't explicitly defined by the resource or resource method (such as are handled in a filter or other processor).

Example:
@GET
@RequestHeaders ({
  @RequestHeader( name = "X-Auth-Token", description = "The authentication token."),
  @RequestHeader( name = "Host", description = "The host header.")
})
Person getPerson(@PathParam("id") String id);

@RequestHeader JavaDoc Tag

Applied to a resource class or a resource method. Used to document the set of request headers that may be included upon invocation of the operation. The request headers annotated on a method are appended to the headers annotated on the defining resource class. Originally defined by jax-doclets.

Example:
/**
 * @RequestHeader X-Auth-Token The authentication token.
 */
@GET
Person getPerson(@PathParam("id") String id);

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 headers annotated on the defining resource class.

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

@ResponseHeader JavaDoc Tag

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 headers annotated on the defining resource class. Originally defined by jax-doclets.

Example:
/**
 * @ResponseHeader Location The location of the created person.
 */
@POST
Person createPerson(Person person);

c.w.e.m.rs.ServiceContextRoot

Applied to a resource class or a resource method. Used to specify a different context root for resources and groups, often used when bundling services with different application paths within an EAR. If resources are grouped by path or by annotation, there exists the possibility of conflicting values for @ServiceContextRoot. In such a case, the algorithm for resolving the conflict is undefined; the first annotation encountered by the processor will be selected.

Example:
@ServiceContextRoot("/context")
@Path("/resource")
public class MyResource {
  ...
}

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

}

@label JavaDoc Tag

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), a resource method, a resource parameter, or a data type.

Used to suggest example value(s). As of Enunciate 2.3, the @DocumentationExample annotation also supports a second value (e.g. @DocumentationExample( value = "male", value2 = "female")) that will be used if the example is used multiple times, such as in the case of arrays.

As of Enunciate 2.8, the @DocumentationExample annotation can also be used to suggest a specific data type to be used, such as when a specific subclass is desired as the example.

Example:
class Person {

  @DocumentationExample("male")
  public String gender;

  @DocumentationExample(type=@TypeHint(Cat.class))
  public Pet pet;

}

@documentationExample JavaDoc Tag

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

Example:
class Person {

  /**
   * @documentationExample male
   */
  public String gender;

}

@documentationType JavaDoc Tag

As of Enunciate 2.8, applied to a data type accessor (field or property) or a resource method, used to suggest a specific data type to be used, such as when a specific subclass is desired as the example.

Example:
class Person {

  /**
   * @documentationType com.mycompany.Cat
   */
  public Pet pet;

}

@jsonExampleOverride JavaDoc Tag

As of Enunciate 2.13, applied to a data type accessor (field or property) or data type, used to completely override the JSON example used in the documentation.

Example:
class SomeClass {

  /**
   * @jsonExampleOverride [{"enum" : { "string" : "string" } }]
   */
  public List<Map<SomeEnumType, Map<String, String>>> someField;

}

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 {

}

@resourceGroup JavaDoc Tag

(Since 2.12)

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

Example:
/**
 * @resourceGroup Person API
 */
@Path("/persons")
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 {

}

c.w.e.m.Style(s)

Applied to a data type, data property, service class, resource class, resource method, or resource resource parameter. Used to apply custom styles to the generated documentation for the specific properties. For more information, see the documentation on creating a custom skin.

Example:
@com.webcohesion.enunciate.metadata.Style("secured")
public Date created
Example:
@com.webcohesion.enunciate.metadata.Styles(
  @com.webcohesion.enunciate.metadata.Style("secured"),
  @com.webcohesion.enunciate.metadata.Style("conditional")
)
public Date created

@style JavaDoc Tag

Applied to a data type, data property, service class, resource class, resource method, or resource resource parameter. Used to apply custom styles to the generated documentation for the specific properties. For more information, see the documentation on creating a custom skin.

Example:
/**
 * @style secured
 * @style conditional
 */
public Date created

@responseExample JavaDoc Tag

(Since 2.9.1)

Applied to a resource method. Used to provide a custom example response body. Requires the media type to which the example is applicable.

If the value starts with "classpath:", it will be interpreted as a reference to a text file on the classpath.

If the value starts with "file:", it will be interpreted as a reference to a text file on the file system.

Example:
/**
 * @responseExample application/json { "name" : "Harry Truman", "birth" : "1884-05-08" }
 * @responseExample application/xml
 *   <person>
 *     <name>Harry Truman</name>
 *     <birth>1884-05-08</birth>
 *   </person>
 */
@GET
Person getPerson(@PathParam("id") String id);
Example:
/**
 * @responseExample application/json file:/path/to/example.json
 * @responseExample application/xml classpath:/reference/to/example.xml
 */
@GET
Person getPerson(@PathParam("id") String id);

@requestExample JavaDoc Tag

(Since 2.9.1)

Applied to a resource method. Used to provide a custom example request body. Requires the media type to which the example is applicable.

If the value starts with "classpath:", it will be interpreted as a reference to a text file on the classpath.

If the value starts with "file:", it will be interpreted as a reference to a text file on the file system.

Example:
/**
 * @requestExample application/json { "name" : "Harry Truman", "birth" : "1884-05-08" }
 * @requestExample application/xml
 *   <person>
 *     <name>Harry Truman</name>
 *     <birth>1884-05-08</birth>
 *   </person>
 */
@POST
void createPerson(Person person);
Example:
/**
 * @requestExample application/json file:/path/to/example.json
 * @requestExample application/xml classpath:/reference/to/example.xml
 */
 @POST
 void createPerson(Person person);

@pathExample JavaDoc Tag

(Since 2.10)

Applied to a resource method. Used to provide a custom request path in the example.

Example:
/**
 * @pathExample /persons?id=12345
 */
@GET
Person getPerson(@QueryParam("id") String id);

c.w.e.m.ReadOnly

As of Enunciate 2.10, applied to a data property. Used to mark a property as "read only".

Example:
@com.webcohesion.enunciate.metadata.ReadOnly
public String id;

@readonly JavaDoc Tag

As of Enunciate 2.10, applied to a data property. Used to mark a property as "read only".

Example:
/**
 * @readonly
 */
public String id;

c.w.e.m.Password

As of Enunciate 2.12, applied to a data property. Used to mark a property as being used to hold a password.

Example:
@com.webcohesion.enunciate.metadata.Password
public String password;

@password JavaDoc Tag

As of Enunciate 2.12, applied to a data property. Used to mark a property as being use to hold a password.

Example:
/**
 * @password
 */
public String password;

Processor Directives

c.w.e.m.Ignore

Applied to a Java class, field, property, or parameter. Used to suggest to Enunciate that the annotated class, field, property, or parameter 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 {

}

@ignore JavaDoc Tag

(Since 2.10)

Applied to a Java class, field, or property. Used to suggest to Enunciate that the annotated class, field, or property 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 {

}

c.w.e.m.json.JsonSeeAlso

Applied to a Java class that defines a JSON type. Used to suggest to Enunciate that other classes should be considered as JSON data types.

Example:
@JsonSeeAlso(
  { OtherJsonObject.class, OtherJsonObject2.class }
)
class MyJsonObject {

}

c.w.e.m.json.JsonStringFormat

(Since 2.13)

Applied to a parameter, field or property. Used to suggest to Enunciate the format of the string that is the value of the parameter, field, or property.

Example:
@JsonStringFormat("date")
public LocalDate localDate;

@jsonStringFormat JavaDoc Tag

(Since 2.13)

Applied to a field or property. Used to suggest to Enunciate the format of the string that is the value of the field, or property.

Example:
/**
 * @jsonStringFormat date
 */
public LocalDate localDate;

© 2023 Web Cohesion

Clone this wiki locally