spring - 阐明 Spring 注释 API 文档

我正在使用 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 的注释？

最佳答案

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

我修改了 docs.xml.fmt 以及 docs.fmt 的 enunciate-docs ，以便识别“@Secured”注释。

不幸的是，对于 docs.xml.fmt ，没有像 docs.fmt 那样干净的自定义方法。所以，我不得不用这些修改过的文件打包自己。

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

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

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

现在，

就在这个块下面:

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

添加另一个 if 块

[#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]

添加以下块

[#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]

关于spring - 阐明 Spring 注释 API 文档，我们在Stack Overflow上找到一个类似的问题：https://stackoverflow.com/questions/17448136/