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.

Enunciate can e.g. create client-side libraries for various technologies, but it can also be used to generate HTML documentation of the analysed REST-API code.

Various modules are available that will analyse (so called provider modules) and generate things. This post is about the spring-web and docs modules, of which the first is able to analyze and provide API-specific information from Spring Web MVC RestController classes and the latter will generate HTML documentation from the analyzed classes.

Add to Gradle

buildscript {
  repositories {
    maven {
      url "https://plugins.gradle.org/m2/"
    }
  }
  dependencies {
    classpath("gradle.plugin.com.webcohesion.enunciate:enunciate-gradle:2.2.0")
  }
}

apply plugin: 'com.webcohesion.enunciate'

There seems to be no configuration object yet. Must configure task directly:

tasks.enunciate {
  File enunciateDistDir = file("dist/docs/api")
  doFirst {
    enunciateDistDir.deleteDir()
    enunciateDistDir.mkdirs()
  }
  export("docs", enunciateDistDir)
}

tasks.enunciate.doFirst { project.delete("build/enunciate") }

Configuration XML

There has to be an enunciate.xml configuration file under src\main\enunciate\enunciate.xml. It must contain at least an empty <enunciate> tag:

<enunciate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://enunciate.webcohesion.com/schemas/enunciate-2.2.0.xsd">

</enunciate>

The specified schema is not used for validation, but it is well documented and allows IDE's such as Eclipse or IntelliJ to provide auto-complete when writing a configuration. The configuration options are described here. The configuration allows to configure things like

• version
• slug
• title
• description
• copyright
• terms
• code-license (for the generated code licenses)
• api-license (governs usage of documented api)
• contact
• application (e.g. base uri)
• api-classes (include/exclude with patterns)
• facets
• namespaces
• modules (sub-configurations for generator modules)

Custom Annotations

Enunciate brings a set of custom annotations that can be used in code to enhance the generated documentation. The annotations can be included into the build with the following gradle dependency:

dependencies {
  compile 'com.webcohesion.enunciate:enunciate-core-annotations:2.2.0'
}

The following annotations have impact on the output of the docs module:

• @Label: Provides a different label for resources and/or data types in the documentation (instead of class name)
• @DocumentationExample: Provide a value for the 'example' JSON
• @ResourceGroup: Provides a tag under which resources (methods and/or resources) are grouped (by default: by class/controller)

Styling of Output

The output may be stlyed with an own CSS which can be specified as an attribute of the <docs> module configuration. Enunciate uses a Freemarker template to generate the HTML output, this template may also be adjusted and provided in a different form, if desired (configuration is also on the <docs> module configuration element).

Client-Libraries

Enunciate generates a set of client libraries (Java, PHP, Ruby). Those files are automatically made available for download on the API pages. If this feature is not desired, the corresponding modules can be disabled in the configuration XML.

Problems and Deficiencies

There seems to be a problem with Spring-MVC's @ResponseCode annotation for resource methods. This annotation throws off the freemarker template of enunciate, see issue #302. Quick fix: use a copy of the default freemarker template that has been fixed to deal with the missing element (configure in enunciate.xml on the <docs> element).

When using the custom Annotations, there will (again) be Annotations in Code that do not have any functional value for the implementation. It would be better if all extra annotations could be used as Javadoc Tags.

Enunciate already supports the JAX-RS Doclet for Javadoc Tags like @HTTP 404 if resource not found to document error response codes. There are also Tags to document any extra headers. Unfortunately, JAX-RS Doclet support is not built into the Spring MVC provider module yet, see issue #306.