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

Question

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

Swagger 似乎是一个非常酷的解决方案，但我不知道如何在我的代码中使用它。我正在寻找创建 json swagger-ui 可以读取的最佳方法 - 我应该怎么做？

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

Answer 1

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

上提供了一些生成文档的示例

更新

项目已移至http://enunciate.webcohesion.com/，即将发布的 2.0 版本将支持 java 8。

Answer 2

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

"您可以按原样使用 swagger-ui 代码！无需构建或 重新编译——只需克隆这个 repo 并使用预先构建的文件 dist 文件夹。如果您喜欢 swagger-ui 的原样，请到此为止。”

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

我怀疑您还有其他一些细节配置错误，这很容易，因为您必须在多个地方配置 Swagger。下面我将详细介绍我自己在 Swagger 中的设置。

这是我的 web.xml 上 Swagger 配置的 sn-p：

<!-- // 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，您应该尝试将其用作“模板”来设置您的 swagger。我遇到问题的一个文件是 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，它的设置非常简单。