Facets

Note: The following applies to Enunciate version 2. For information regarding facets in Enunciate 1.x, see Facets (Version 1)

Enunciate Facets

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.

You can think of a facet as a kind 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.

Applying Facets

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

• com.webcohesion.enunciate.metadata.Facet - used to apply a single facet to an API component.
• com.webcohesion.enunciate.metadata.Facets - used to apply multiple facets to an API component.

The Facet annotation allows you to provide a name and some documentation associated with the facet.

In addition to the annotations, facets can be applied to classes using Enunciate configuration:

<enunciate ...>
  ...
  <api-classes>
    <facet name="admin" pattern="com.mycompany.admin.**"/>
    <facet name="admin" pattern="com.mycompany.dto.AdminDto"/>
  </api-classes>
  ...
</enunciate>

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( "http://mycompany.com/facets#admin" )
public @interface Admin {
 ...
}

Applying the above annotation to any API component will apply a facet ("http://mycompany.com/facets#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>