发布Spring annotations API文档

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

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

我尝试使用具有spring支持maven-enunciate-spring-plugin的maven工件生成文档,但它甚至不生成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以及enunciate-docs的docs.fmt,以便识别’@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]
上一篇:什么是标准的Python文档字符串格式?


下一篇:python – Sphinx会使用不能很好导入的代码吗?