Enunciate Spring annotations API documentation

Question

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?

Answer 1

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]

Answer 2

I'm afraid not. Enunciate doesn't recognize those Spring annotations, although that feature could be added. You're welcome to open up a request for it.

(The maven-enunciate-spring-plugin is just used to have Enunciate wire in Spring to the back-end runtime, it doesn't include the feature you're asking about.)