Custom Skin

Note: The following applies to Enunciate version 2. For applying a custom skin to Enunciate 1.x, see Custom Skin (Version 1)

Applying a Custom Skin to Enunciate's Documentation

Enunciate generates its documentation by passing the data model provided by the "provider" modules (see Modules) through a Freemarker Template, which is used to write out the HTML files to a directory. After the HTML files are generated, Enunciate copies a set of "static assets" (images, css, javascript, etc.) into the directory. The set of static assets is referred to as the "documentation base".

There are multiple levels of customization that you can leverage when applying a different skin to Enunciate's generated documentation. From simplest-but-least-powerful to most-complex-but-most-powerful, these are:

• Replace the default CSS stylesheet.
• Provide additional CSS stylesheet(s).
• Provide a custom documentation base.
• Provide a custom Freemarker template.

Each of these customization points can be provided in one of two ways:

• The Enunciate configuration file.
• Classpath lookup, such that you can just include a jar on your Enunciate build classpath and Enunciate will automatically "find" your custom skin.

Custom CSS stylesheet

If you're happy enough with just adjusting some colors and fonts, you can apply your own CSS file(s) to the Enunciate-generated documentation.

Custom CSS Via Enunciate Configuration File

<enunciate>
 <modules>
   <docs css="/path/on/filesystem/to/custom.css">
     <additional-css file="/path/to/additional.css"/>
   </docs>
 </modules>
</enunciate>

Custom CSS Via Classpath Lookup

Enunciate will look for a file at /META-INF/enunciate/css/style.css on your classpath. If that file is found, it will be used as your custom CSS file.

Default Microdata Styles

In addition to the standard bootstrap styles, the default generated documentation annotates certain elements with preset CSS styles:

style name	description
datatypes	(Since 2.7) Applied to the table that lists the data types.
datatype-name	Applied to the text that contains the data type name.
datatype-description	Applied to the text that contains the data type description.
datatype-reference	Applied to the text that contains a reference to a data type.
datatype-properties	(Since 2.7) Applied to the table that lists the data type properties.
datatype-values	(Since 2.7) Applied to the table that lists the data type values.
downloadfiles	(Since 2.7) Applied to the table that lists the available download files.
downloadfile-name	Applied to the text that contains the download file name.
downloadfile-size	Applied to the text that contains the download file size.
downloadfile-description	Applied to the text that contains the download file description.
fault-name	Applied to the text that contains the service fault name.
fault-conditions	Applied to the text that contains the service fault conditions.
header-name	Applied to the text that contains the request/response header name.
header-description	Applied to the text that contains the request/response header description.
parameter-name	Applied to the text that contains the parameter name.
parameter-description	Applied to the text that contains the parameter description.
parameter-default-value	Applied to the text that contains the parameter default value.
parameter-constraints	Applied to the text that contains the parameter constraints.
parameter-multivalued	Applied to the text that contains the indicator for whether the parameter is multi-valued.
property-name	Applied to the text that contains the data type property name.
property-description	Applied to the text that contains the data type property description.
request-type	Applied to the text that contains the request media type.
response-condition	Applied to the text that contains the response condition.
response-description	Applied to the text that contains the response description.
response-type	Applied to the text that contains the response type.
resources	(Since 2.7) Applied to the table that lists the API resources.
resource-path	Applied to the text that contains the resource path.
resource-method	Applied to the text that contains the resource method.
resource-description	Applied to the text that contains the resource description.
resource-parameters	(Since 2.7) Applied to the table that lists the resource parameters.
resource-response-body	(Since 2.7) Applied to the table that describes the resource response body.
resource-response-codes	(Since 2.7) Applied to the table that lists the resource response codes.
resource-response-headers	(Since 2.7) Applied to the table that lists the resource response headers.
resource-response-warnings	(Since 2.7) Applied to the table that lists the resource response warnings.
services	(Since 2.7) Applied to the table that lists the API services.
service-name	Applied to the text that contains the service name.
service-description	Applied to the text that contains the service description.
service-faults	(Since 2.7) Applied to the table that lists the service faults.
service-input-parameters	(Since 2.7) Applied to the table that lists the service input parameters.
service-output-parameters	(Since 2.7) Applied to the table that lists the service output parameters.
service-return-value	(Since 2.7) Applied to the table that describes the service return value.
syntax-name	Applied to the text that contains the syntax name.
value-value	Applied to the text that contains the data type value.
value-description	Applied to the text that contains the data type value description.
warning-code	Applied to the text that contains the warning code.
warning-condition	Applied to the text that contains the warning condition.

Providing Custom Styles

As of Enunciate 2.4, you can annotate data types, properties, services, resources, methods, parameters, etc. in such a way that Enunciate will apply a custom CSS style to the names of these elements in the generated documentation.

@com.webcohesion.enunciate.metadata.Style("secured")
public Date created

Will have the "secured" CSS style applied to its name in the documentation:

<tr>
  <td><span class="property-name secured">created</span></td>
  ...
</tr>

Or you can provide multiple styles:

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

Or you can use JavaDoc:

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

Or you can provide your own annotations:

@Style("secured")
public @interface Secured {
}

Or you can configure custom annotations:

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

Custom Documentation Base

A "documentation base" is the set of files that are used and referenced by the generated documentation, e.g. images and javascript files.

Custom Docs Base Via Enunciate Configuration File

<enunciate>
 <modules>
   <docs base="/path/on/filesytem/to/zip/or/dir"/>
 </modules>
</enunciate>

Custom Docs Base Via Classpath Lookup

Enunciate will look for a file at /META-INF/enunciate/docs-base.zip on your classpath. If that file is found, it will be used as your custom documentation base.

Custom Freemarker Transform

If you need custom HTML, you will have to provide a custom Freemarker transform that will do what you need. The easiest way to do this probably to start with Enunciate's default Freemarker template and edit it according to your needs. You'll want to refer to the Freemarker docs.

You may be interested in the directory of custom themes to browse themes the community has contributed. And please feel free to contribute your own.

Custom Freemarker Transform Via Enunciate Configuration File:

<enunciate>
 <modules>
   <docs freemarkerTemplate="/path/on/filesytem/to/template.fmt"/>
 </modules>
</enunciate>