spring - 阐述 Spring 注解 API 文档

Question

我正在使用 Enunciate 在 Maven 项目中生成 REST API 文档。

Artifact maven-enunciate-plugin 生成 Web API 文档，但它忽略了 Spring 注释，例如:@Secured(来自 spring-security)

我尝试使用支持 spring maven-enunciate-spring-plugin 的 Maven Artifact 生成文档，但它甚至不生成 Web API 文档。

有没有办法配置 enunciate 或使用另一个 enunciate maven 插件，以便在 Enunciate 生成的文档中识别和提及来自 Spring 的注释？

Answer 1

没关系，我通过“将自定义皮肤应用到 Enunctiate 的文档”(http://docs.codehaus.org/display/ENUNCIATE/Applying+a+Custom+Skin+to+Enunciate%27s+Documentation)设法解决了这个问题

我修改了 docs.xml.fmt 以及 enunciate-docs 的 docs.fmt，所以 '@Secured' 注解是认可。

不幸的是，对于 docs.xml.fmt，没有像我们为 docs.fmt 那样进行自定义的简洁方法。所以，我不得不用这些修改后的文件打包自己。

我引用了@Deprecated(java.lang.Deprecated)是如何处理的，遵循了类似的方法。

在 docs.fmt 文件中，将此 block 添加到 isDeprecated 的类似功能 block 下方

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

现在，

就在这个 block 下面:

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

添加另一个 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]

现在，在 docs.xml.fmt 文件中，就在下面:

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

添加以下 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]