Question

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

工件maven-enunciate-plugin生成Web API文档，但忽略了Spring注释，如：@Secured（来自spring-security）

我尝试使用具有弹簧支持maven-enunciate-spring-plugin的maven工件生成文档，但它甚至不生成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以及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]

Answer 2

我不敢。虽然可以添加该功能，但Enunciate无法识别这些Spring注释。欢迎您open up a request来获取它。

（maven-enunciate-spring-plugin仅用于在Spring中将Enunciate wire连接到后端运行时，它不包括您要询问的功能。）

发布Spring annotations API文档

2 个答案: