使用swagger或任何其他工具生成Rest API文档

Question

我正在寻找一种记录我的Rest API的方法。 我的服务器是Tomcat / Spring服务器，Rest API是使用Jenkins实现的。

Swagger似乎是一个非常酷的解决方案，但我无法弄清楚如何将它与我的代码一起使用。我正在寻找创造json swagger的最好方法 - ui可以阅读 - 我该怎么做？

此外，我很乐意检查在此类环境中记录Rest API的任何其他好的解决方案。

Answer 1

我没有尝试过招摇，但你可以试试enunciate。它可以生成JAX-RS端点的文档，作为javadoc阶段的一部分。有关生成文档的一些示例，请参见enunciate page

<强>更新

Project已移至http://enunciate.webcohesion.com/，即将推出的2.0版将支持java 8。

Answer 2

要启用swagger-ui，您可以“按原样”使用它 - 来自文档：

  

“你可以使用swagger-ui代码AS-IS！无需构建或   重新编译 - 只需克隆此repo并使用预先构建的文件   dist文件夹。如果你喜欢swagger-ui as as is，请停在这里。“

所以基本上你只需要在你的web服务器中放置“dist”内容，然后在UI中输入你的web服务的swagger端点，例如：http://localhost:8080/Webservice/api-doc.json（这是相同的地址端点你必须在你的web.xml中定义）。

我怀疑你有一些错误配置的其他细节，这很容易，因为有几个地方你必须配置Swagger。在下文中，我将向您介绍我在Swagger中设置的一些细节。

这是我的web.xml上Swagger配置的片段：

<!-- // Jersey declaration -->
<servlet>
    <servlet-name>web service</servlet-name>
    <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
    <init-param>
        <param-name>com.sun.jersey.config.property.packages</param-name>
        <param-value>com.mywebservice;com.wordnik.swagger.jaxrs.listing;com.fasterxml.jackson.jaxrs</param-value>
    </init-param>
    <init-param>
        <param-name>com.sun.jersey.config.property.classnames</param-name>
        <param-value>com.mywebservice;com.wordnik.swagger.jaxrs.listing;com.fasterxml.jackson.jaxrs</param-value>
    </init-param>
    <init-param>
        <param-name>swagger.api.basepath</param-name>
        <param-value>http://localhost:8080/Webservice</param-value>
    </init-param>
    <init-param>
        <param-name>api.version</param-name>
        <param-value>0.0.2</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>
<servlet>
    <servlet-name>Bootstrap</servlet-name>
    <servlet-class>com.mywebservice.utils.swagger.Bootstrap</servlet-class>
    <load-on-startup>1</load-on-startup>
</servlet>
<filter>
    <filter-name>ApiOriginFilter</filter-name>
    <filter-class>com.mywebservice.utils.swagger.ApiOriginFilter</filter-class>
</filter>
<filter-mapping>
    <filter-name>ApiOriginFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

Bellow是com.mywebservice.utils.swagger包的列表，其中有几个资源，如Swagger文档中所示（现在看起来与我设置时不同，所以这里是完整的文档列表）：

您可以在Swagger的示例项目中找到这些文件（或示例）：https://github.com/wordnik/swagger-core/tree/master/samples/java-jaxrs，您应该尝试将其用作“模板”来设置您的招摇。我遇到麻烦的一个文件是ApiListingResource：

import javax.ws.rs.Path;
import javax.ws.rs.Produces;

import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.jaxrs.JavaApiListing;

@Path("/resources.json")
@Api("/resources")
@Produces({ "application/json"})
public class ApiListingResource extends JavaApiListing{
}

HTH。

Answer 3

如果您正在使用JAX-RS和maven，您可以考虑尝试MireDot，这非常容易设置。