-
Notifications
You must be signed in to change notification settings - Fork 201
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)
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).
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.
@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))
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.
/**
* @HTTP 404 If the person is not found.
*/
@GET
@Path("person/{id}")
Person readPerson(@PathParam("id") String id);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.
@GET
@Path("person/{id}")
@Warnings ({
@ResponseCode ( code = 299, condition = "The reason the person wasn't found, if applicable.")
})
Person readPerson(@PathParam("id") String id);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.
/**
* @HTTPWarning 299 The reason the person wasn't found, if applicable.
*/
@GET
@Path("person/{id}")
Person readPerson(@PathParam("id") String id);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 jakarta.ws.rs.core.Response.) The TypeHint annotation is used to give Enunciate a hint about what is to be returned or consumed.
@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);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 jakarta.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.
/**
* @returnWrapped com.mycompany.Person
*/
@GET
@Path("person/{id}")
Person readPerson(@PathParam("id") String id);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.
/**
* @inputWrapped com.mycompany.Person
*/
@POST
@Path("person/{id}")
Person updatePerson(InputStream data);(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).
@GET
@RequestHeaders ({
@RequestHeader( name = "X-Auth-Token", description = "The authentication token."),
@RequestHeader( name = "Host", description = "The host header.")
})
Person getPerson(@PathParam("id") String id);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.
/**
* @RequestHeader X-Auth-Token The authentication token.
*/
@GET
Person getPerson(@PathParam("id") String id);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.
@POST
@ResponseHeaders (
@ResponseHeader( name = "Location", description = "The location of the created person.")
)
Person createPerson(Person person);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.
/**
* @ResponseHeader Location The location of the created person.
*/
@POST
Person createPerson(Person person);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.
@ServiceContextRoot("/context")
@Path("/resource")
public class MyResource {
...
}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.
@Label ("PersonRelativeAge")
enum Age {
old,
young
}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.
/**
* @label PersonRelativeAge
*/
enum Age {
old,
young
}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.
class Person {
@DocumentationExample("male")
public String gender;
@DocumentationExample(type=@TypeHint(Cat.class))
public Pet pet;
}Applied to a data type accessor (field or property) or a data type. Used to suggest an example value for XML/JSON examples.
class Person {
/**
* @documentationExample male
*/
public String gender;
}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.
class Person {
/**
* @documentationType com.mycompany.Cat
*/
public Pet pet;
}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.
class SomeClass {
/**
* @jsonExampleOverride [{"enum" : { "string" : "string" } }]
*/
public List<Map<SomeEnumType, Map<String, String>>> someField;
}Applied to a resource class or a resource method. Used to customize how resources are grouped in the documentation. See Module-JAXRS.
@Path("/persons")
@ResourceGroup("Person API")
class PersonResource {
}(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.
/**
* @resourceGroup Person API
*/
@Path("/persons")
class PersonResource {
}Applied to a resource class or a resource method. Used to customize how resources or resource methods are labeled in the generated documentation.
@Path("/persons")
@ResourceLabel("Person Resource")
class PersonResource {
}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.
@com.webcohesion.enunciate.metadata.Style("secured")
public Date created@com.webcohesion.enunciate.metadata.Styles(
@com.webcohesion.enunciate.metadata.Style("secured"),
@com.webcohesion.enunciate.metadata.Style("conditional")
)
public Date createdApplied 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.
/**
* @style secured
* @style conditional
*/
public Date created(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.
/**
* @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);/**
* @responseExample application/json file:/path/to/example.json
* @responseExample application/xml classpath:/reference/to/example.xml
*/
@GET
Person getPerson(@PathParam("id") String id);(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.
/**
* @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);/**
* @requestExample application/json file:/path/to/example.json
* @requestExample application/xml classpath:/reference/to/example.xml
*/
@POST
void createPerson(Person person);(Since 2.10)
Applied to a resource method. Used to provide a custom request path in the example.
/**
* @pathExample /persons?id=12345
*/
@GET
Person getPerson(@QueryParam("id") String id);As of Enunciate 2.10, applied to a data property. Used to mark a property as "read only".
@com.webcohesion.enunciate.metadata.ReadOnly
public String id;As of Enunciate 2.10, applied to a data property. Used to mark a property as "read only".
/**
* @readonly
*/
public String id;As of Enunciate 2.12, applied to a data property. Used to mark a property as being used to hold a password.
@com.webcohesion.enunciate.metadata.Password
public String password;As of Enunciate 2.12, applied to a data property. Used to mark a property as being use to hold a password.
/**
* @password
*/
public String password;As of Enunciate 2.15, applied to a data property or a request parameter. Used to document specific string values to a given enum subset.
@com.webcohesion.enunciate.metadata.AllowedValues(Ops.class)
public String ops;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.
@Ignore
class PersonUtils {
}(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.
/**
* @ignore
*/
class PersonUtils {
}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.
@JsonSeeAlso(
{ OtherJsonObject.class, OtherJsonObject2.class }
)
class MyJsonObject {
}(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.
@JsonStringFormat("date")
public LocalDate localDate;(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.
/**
* @jsonStringFormat date
*/
public LocalDate localDate;(Since 2.14)
Applied to a resouce method. Used to specify the operation id in the Swagger output.
@OperationId("myOperation")
public void myOperation() {}