Search code examples
springmavendocumentationenunciate

Enunciate Spring annotations API documentation

I am using Enunciate to generate REST API docs in a maven project.

The artifact maven-enunciate-plugin generates Web API docs but it ignores Spring annotations like: @Secured (from spring-security)

I tried generating docs with maven artifact that has spring support maven-enunciate-spring-plugin, but it does not even generate Web API docs.

Is there a way to configure enunciate or use another enunciate maven plugin so that annotations from Spring are recognized and mentioned in the documentation generated by Enunciate?

Solution

  • Nevermind, I managed to solve this problem by "applying a custom skin to Enunctiate's documentation" (http://docs.codehaus.org/display/ENUNCIATE/Applying+a+Custom+Skin+to+Enunciate%27s+Documentation)

    I modified docs.xml.fmt as well as docs.fmt of enunciate-docs, so that '@Secured' annotation is recognized.

    Unfortunately, for docs.xml.fmt, there is no clean way to customize as we have for docs.fmt. So, I had to package myself with these modified files.

    I referred to how @Deprecated (java.lang.Deprecated) was processed and followed the similar method.

    In docs.fmt file, add this block just below similar function block of isDeprecated

    [#function isSecured element]
  [#return (getTagValues(element, "secured")?size > 0)/]
[/#function]

    Now,

    Just below this block:

    [#if isDeprecated(resource)]
 <p class="alert">This resource has been deprecated.</p>
[/#if]

    add another if block

    [#if isSecured(resource)]
  <p class="note">This resource is available only to these roles:  
  [#assign securedTags = getTagValues(resource, "secured") /]
  [#if securedTags?size > 0]
    ${securedTags[0]}
  [/#if]

  [#list resource.parent.annotations as tag]
      ${tag}
  [/#list]
  </p>
[/#if]

    Now, in docs.xml.fmt file, just below:

    [#if resource.parent.annotations["java.lang.Deprecated"]??]
  <tag name="deprecated"/>
[/#if]

    Add following block

    [#if resource.parent.annotations["org.springframework.security.access.annotation.Secured"]??]
  <tag name="secured">

    [#list resource.parent.annotations["org.springframework.security.access.annotation.Secured"]["value"] as roles]
      <![CDATA[${roles}]]> 
    [/#list]

  </tag>
[/#if]