User Guide

Note: The following is applicable to Enunciate 2. For Enunciate 1.x executables, see User Guide (Version 1).

Welcome to the Enunciate user guide.

The Enunciate Engine

Enunciate can be considered like a Java compiler that produces Web service tools and documentation instead of bytecode. Enunciate is invoked with a classpath, a sourcepath, and a set of source files that is passed to the javac tool, which Enunciate uses to get its work done. Before the javac tool is invoked, the classpath, sourcepath, and source files are scanned to discover a list of elements that are interesting to the various Enunciate modules. This list of elements is made available to each module, which processes the list according to its function.

For more information about how the list of API elements can be filtered, see Configuration below.

Enunciate Modules

The work of Enunciate is divided into modules. Modules are loosely coupled, loosely-interdependant extensions to the Enunciate engine. Each module has a specific set of work to perform, and each module can be separately configured (including disabled) in the Enunciate configuration file.

See Modules for more information about Enunciate modules, including information about specific modules and how to write a custom Enunciate module.

Configuration

Configuration for the Enunciate engine (including any of its modules) is done in a single XML file that conforms to this schema. The configuration is defined by a top-level <enunciate> element.

<?xml version="1.0" encoding="UTF-8"?>
<enunciate
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="http://enunciate.webcohesion.com/schemas/enunciate-2.18.0.xsd">
...
</enunciate>

Here are some of the more interesting attributes applicable to the <enunciate> element.

attribute	description
slug	The "slug" attribute of the root element specifies a unique identifier for your Enunciate project. A slug is useful because it is what often determines the names of some of the Enunciate-generated artifacts. For example, the names of your client-side libraries will be based on the slug. The default slug is "api". For Maven users, the default slug is the project artifact id.
version	The "version" attribute specifies a version for the API. A version is often useful to clients who need to know whether they're on the latest version of the API, or using the latest version of an Enunciate-generated client. For Maven users, the default version is the project version.

The <enunciate> element also is configured with the following child elements. Note that not all configuration elements are listed here, but may be documented in other places like the FAQ.

title

A title for your project. For Maven users, the default title is the project name.

description

A description for your project. For Maven users, the default title is the project description. If you want to add HTML markup for formatting, hyperlinks etc. in your description you can use CDATA.

<enunciate ...>
  ...
  <description>
    <![CDATA[
      <h1>Your headline</h1>
      <p>Your tagline and a <a href="http://your.homepage.url">link to more details</a></p>
    ]]>
  </description>
  ...
</enunciate>

The description element also supports the following attributes:

attribute	description
package	The package that contains package-info with the text of the description.
file	A file that contains text of the description.
format	(As of version 2.9) The format of the description: "markdown" or "html". Default: "html".

<enunciate ...>
  ...
  <description file="/path/to/my/description.html"/>
  ...
</enunciate>

copyright

A copyright for the documentation and generated code.

terms

The terms of use that govern the use of the API being documented.

code-license

The license that governs the use of the generated code libraries.

api-license

The license that governs the use of the API being documented. For Maven users, the default license is the license provided in the pom.

contact

Information about how to contact someone about using the documented API. For Maven users, the default contact list is the list of contributors provided in the pom.

application

Information about the application that hosts the documented API. This is mostly used to configure a "base URI" for the API that can be used by the documentation and client-side code.

api-classes

The api-classes element can be used to exclude or include elements that are provided to the Enunciate engine. For more information, see Excluding Including Classes.

<enunciate ...>
  ...
  <api-classes>
    <exclude pattern="com.mycompany.hide.**"/>
    <include pattern="com.mycompany.hide.ExceptThisClass"/>
    <exclude pattern="com.mycompany.api.MyClass"/>
  </api-classes>
  ...
</enunciate>

facets

The facets element is used to configure how API facets are to be used in the project, such as to exclude certain API components from the generated documentation and client-side code. For more information, see Facets.

<enunciate>
  ...
  <facets>
    <include name="Public"/>
    <exclude name="Admin"/>
  </facets>
  ...
</enunciate>

styles

The styles element is used to configure styles that can be applied to specific aspects of the generated documentation. For more information, see the documentation on creating a custom skin.

<enunciate>
  ...
  <styles>
    <annotation name="org.apache.shiro.authz.annotation.RequiresAuthentication" style="secured"/>
  </styles>
  ...
</enunciate>

namespaces

The namespaces element is used to define the prefixes for your namespaces. For more information, see Custom Namespace Prefixes.

modules

The modules element contains the configuration of each module. For more information, see Modules.