Facets (Version 1)

Note: The following applies to Enunciate version 1.x. For using Facets in Enunciate 2, see Facets

Enunciate Facets

As of version 1.27, Enunciate provides a way to apply "facets" to components of your API, including:

• SOAP endpoints
• Methods on SOAP endpoints
• JAX-RS (REST) endpoints
• Methods on JAX-RS endpoints (note "Default Facets on JAX-RS Methods" note below)
• JAXB data types and root elements
• Accessors (a.k.a. "members" or "properties") of JAXB data types.

A "facet" is just a name-value pair. You can think of a facet as a type of a tag.

Facets are used to identify a related set of API components. For example, you may want to identify an "admin" facet that identifies the API components that are applicable to admin access to your API.

Default Facets on JAX-RS Methods

JAX-RS methods all have a default facet named "org.codehaus.enunciate.contract.jaxrs.Resource" applied to them. The value of this facet is the simple name of the resource class that declares the method.

Applying Facets

Enunciate provides the following annotations that are used to apply facets to your API:

• org.codehaus.enunciate.Facet - used to apply a single facet to an API component.
• org.codehaus.enunciate.Facets - used to apply multiple facets to an API component.

The Facet annotation allows you to provide a name and a value as well as some documentation associated with the facet. The value is an optional annotation parameter; by default the (simple) name of the member to which the annotation applies will be used as the facet value.

Custom Facet Annotations

You can also define your own facet annotations:

package com.mycompany;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target ( { ... } )
@Retention ( RetentionPolicy.RUNTIME )
@Facet( name = "http://mycompany.com/facets#admin" )
public @interface Admin {
 ...
}

Applying the above annotation to any API component will apply a facet (name="http://mycompany.com/facets#admin" and value="Admin") to that component.

What Facets Can Do

Excluding Facets From Generated Code and Docs

Modules that generate code and/or documentation can be configured to exclude facets from their generated artifacts. You can apply "global" facet excludes under the root element of the enunciate.xml configuration file, e.g.:

<enunciate ...>
 ...
 <facets>
   <!-- exclude all components with the facet "http://mycompany.com/facets#admin" applied. -->
   <exclude name="http://mycompany.com/facets#admin"/>
 </facets>
 ...
</enunciate>

Or you can exclude facets from specific modules that support facets. The following example will exclude the "http://mycompany.com/facets#private" facet from all supporting modules and exclude the "http://mycompany.com/facets#admin" facet from just the generated documentation:

<enunciate ...>
 ...
 <facets>
   <!-- exclude all components with the facet "http://mycompany.com/facets#private" applied. -->
   <exclude name="http://mycompany.com/facets#private"/>
 </facets>

 ...

 <modules>
   ...
   <docs ...>
     <facets>
       <!-- exclude all components with the facet "http://mycompany.com/facets#admin" applied. -->
       <exclude name="http://mycompany.com/facets#admin"/>
     </facets>
   </docs>
   ...
 </modules>
</enunciate>

Grouping JAX-RS (REST) Resources in Documentation

Facets are used to group REST resources together. By default, the REST resources are grouped by the org.codehaus.enunciate.contract.jaxrs.Resource facet. You can change that as needed:

<enunciate ...>

 ...

 <modules>
   ...
   <!-- group documentation by the facet "http://mycompany.com/facets#resources" applied. -->
   <docs groupRestResources="http://mycompany.com/facets#resources">
     ...
   </docs>
   ...
 </modules>
</enunciate>