使用Swagger或其他工具生成Rest API文档

Question

使用Swagger或其他工具生成Rest API文档

javarestjerseydocumentation-generationswagger

9

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

Swagger似乎是一个很酷的解决方案，但我不知道如何将其与我的代码结合使用。我正在寻找创建json swagger-ui可以读取的最佳方法 - 我应该如何做到这一点？

此外，在这种环境中记录Rest API的任何其他好的解决方案我都很乐意尝试。

- Erik Sapir

抱歉，能否重新表达你的问题？我无法理解你的问题。 - ritesh

3个回答

5

要启用swagger-ui，你可以直接使用文档中提供的现成代码，不需要编译或重新构建。只需克隆该存储库并使用dist文件夹中的预构建文件即可。如果你喜欢现有的swagger-ui，则无需进行其他操作。

因此，你只需要将“dist”文件夹的内容放置在Web服务器中，然后在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>

以下是com.mywebservice.utils.swagger包的列表，其中有几个资源，如Swagger文档中所示（现在似乎与我设置时不同，因此这里是完整的文档列表）： enter image description here

您可以在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.

- emgsilva

你是使用Ant还是Maven来构建你的应用程序？ - Erik Sapir

我也试图做同样的事情，但是我无法弄清楚实际的JSON文件是如何创建的。 - Erik Sapir

我使用Maven，但这应该没有太大的区别...你说的“找出实际的JSON文件是如何创建的”是什么意思？如果你已经配置好了（类似于我上面的配置），你应该能够通过部署的“.war”链接访问文档（如果你使用Eclipse，可以尝试在其中进行测试，例如使用Tomcat）。确保你有swagger.api.basepath与你部署的.war的“端点”一致，如果不同，它将无法工作...但也许你应该提供更多细节来帮助你进一步！ - emgsilva

我没有使用WAR文件，而是仅生成JAR文件。我不确定swagger.api.basepath应该是什么。另外，你是使用Swagger JAR文件还是将实际代码添加到项目中？ - Erik Sapir

JSON文件是什么时候生成的？我错过了这一部分 - 需要有某种东西来实际创建它们，对吧？ - Erik Sapir

你难道不是在使用Jersey开发Web服务（REST API）吗？如果是这样，在某个给定的时间点，你将部署它（作为.war或.ear），以便为客户提供服务。通常情况下，使用Swagger（如我所配置的那样），只有在Web服务运行时才能在Swagger-UI（或其他客户端）上获取“JSON文件”。基本上，Web服务正在“即时生成”“JSON文件”。或者，也许这就是你要寻找的，有这个项目：https://github.com/ryankennedy/swagger-jaxrs-doclet，旨在“生成适合馈送到swagger-ui的Swagger资源列表”。 - emgsilva

4

如果您正在使用JAX-RS和Maven，您可能也考虑尝试使用MireDot，它非常容易设置。

- Peter R.

看起来不错，但是我无法立即看到商业使用的定价信息，这并没有真正激发太多信任感... - Roland Tepp

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- ragnor · Accepted Answer

我没有尝试过Swagger，但您可以尝试使用Enunciate。它可以作为javadoc阶段的一部分生成JAX-RS端点的文档。一些已生成文档的示例可在Enunciate页面上找到。

更新

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