enunciate

articulate your web api.

Documentation Module

The documentation deployment module is responsible for generating the documentation for the API. This includes both the HTML pages and any other static content, e.g. client libraries.

The order of the documentation module is 100, essentially putting it after the generation of any static documents (e.g. WSDL, schemas) or static downloads (e.g. client libraries), but before the assembly of the war (see the spring-app module, order 200).

Steps

The only significant steps in the documentation module are the "generate" step and the "build" step.

generate

During the generate step, the documentation deployment module generates an XML file that conforms to this schema containing all the documentation for the entire API in a structured form.

build

The build step is where all the documentation files are generated as needed and assembled into a single directory. The first step is to copy the static files (the "base") to the build directory. The documentation base can be specified in the configuration, or you can use the default base.

Then, the documentation module generates another XML file conforming to this schema that contains the information for the files available for download in a structured form. By default, all named artifacts are included as a download (see the architecture guide for details). Other downloads can also be specified in the configuration.

Finally, the XML generated in the generate phase and the XML generated for the download files is processed together to create the static documentation elements. By default, a Freemarker Processing Template is applied to process the XML. You can supply your own Freemarker processing template in the configuration, or you can supply a custom an XML Stylesheet Transformation to generate your site documentation. Click here to see the default Freemarker XML Processing Template used by Enunciate, which might be helpful as a starter for you to create your own custom one. Click here for an example XSLT file.

Configuration

The configuration for the documentation deployment module is specified by the "docs" element under the "modules" element in the Enunciate configuration file.

attributes

  • The "docsDir" attribute is the subdirectory to which the documentation will be put. The default is the root.
  • The "splashPackage" attribute specifies the package that contains the documentation to use as the introduction to the API documentation. By default, no text is used for the introduction.
  • The "copyright" attribute specifies the text for the copyright holder on the web page. By default, there is no copyright information displayed on the webpage.
  • The "title" specifies the title of the generated HTML pages. By default, the title is "Web API".
  • The "includeDefaultDownloads" is a boolean attribute specifying whether the default downloads should be included. The default is "true".
  • The "includeExampleXml" is a boolean attribute specifying whether example XML should be included. The default is "true".
  • The "includeExampleJson" is a boolean attribute specifying whether example JSON should be included. The default is "true" if jackson-xc is on the classpath and "false" otherwise.
  • The "css" attribute is used to specify the file to be used as the cascading stylesheet for the HTML. If one isn't supplied, a default will be provided.

  • The "indexPageName" attribute is used to specify the name of the generated index page. Default: "index.html"
  • The "xslt" attribute specifies the file that is the XML Stylesheet Transform that will be applied to the documentation XML to generate the HTML docs. If no XSLT is specified, the freemarker XML processing template will be used to process the XML.

  • The "xsltURL" attribute specifies the URL to the XML Stylesheet Transform that will be applied to the documentation XML to generate the HTML docs. If no XSLT is specified, the freemarker XML processing template will be used to process the XML.

  • The "freemarkerXMLProcessingTemplate" attribute specifies the file that is the freemarker XML processing template to use to generate the site. See the Freemarker XML Processing Guide. If none is supplied, a default one will be used.
  • The "freemarkerXMLProcessingTemplateURL" attribute specifies the URL to the freemarker XML processing template to use to generate the site. See the Freemarker XML Processing Guide. If none is supplied, a default one will be used.
  • The "freemarkerDocsXMLTemplate" attribute specifies the file that is the freemarker template to use to generate the docs.xml. If none is supplied, a default one will be used.
  • The "freemarkerDocsXMLTemplateURL" attribute specifies the URL to the freemarker template to use to generate the docs.xml. If none is supplied, a default one will be used.
  • The "base" attribute specifies a gzipped file or a directory to use as the documentation base. If none is supplied, a default base will be provided.
  • The "javadocTagHandling" attribute is used to specify the handling of JavaDoc tags. It must be either "OFF" or the FQN of an instance of net.sf.jelly.apt.util.JavaDocTagHandler
  • The "applyWsdlFilter" attribute specifies whether to apply a filter for the WSDL files that will attempt to resolve the soap paths dynamically. Default: "true".
  • The "applyWadlFilter" attribute specifies whether to apply a filter for the WADL files that will attempt to resolve the rest paths dynamically. Default: "true".
  • The "groupRestResources" attribute specifies the name of a facet by which REST resources are grouped together. Default: "org.codehaus.enunciate.contract.jaxrs.Resource".

The "download" element

There can be any number of "download" elements specified. This element is used to indicate another file or Enunciate artifact that is to be included in the "downloads" page. The download element supports the following attributes:

  • The "name" attribute specifies a name for the download.
  • The "artifact" attribute specifies the id of an Enunciate artifact that is to be included as a download.
  • The "file" attribute specifies a file on the filesystem that is to be included as a download. This attribute is ignored if the "artifact" attribute is set.
  • The "description" attribute includes a description of the download. This attribute is ignored if the "artifact" attribute is set.

The "additional-css" element

You can apply additinoal css files to the generated documentation. Use the "file" attribute to specify the additional css file to apply.

The "facets" element

The "facets" element is applicable to the documentation module to configure which facets are to be included/excluded from the documentation artifacts. For more information, see API Facets

Artifacts

docs

The documentation deployment module exports only one artifact: the build directory for the documentation. The artifact id is "docs", and it is exported during the "build" step.

Flattr this