[英]Generating Rest API documentation using swagger or any other tool
我正在寻找一种记录我的Rest API的方法。 我的服务器是Tomcat / Spring服务器,其余的API使用Jenkins实现。
Swagger似乎是一个很酷的解决方案,但我不知道如何在我的代码中使用它。 我正在寻找创建json swagger-ui可以读取的最佳方法-我应该怎么做?
此外,我很乐意在此环境下检查其他任何用于记录Rest API的好的解决方案。
我还没有试过招摇,但你可以尝试字正腔圆 。 作为javadoc阶段的一部分,它可以生成JAX-RS端点的文档。 生成的文档的一些示例可在说明页面上找到
更新资料
项目已移至http://enunciate.webcohesion.com/ ,即将推出的2.0版将支持Java 8。
要启用swagger-ui,您可以按原样使用它-从文档中:
“您可以使用swagger-ui代码AS-IS!无需构建或重新编译-只需克隆此存储库并使用dist文件夹中的预构建文件即可。如果您喜欢swagger-ui,请在此处停止。 ”
因此,基本上,您只需要在Web服务器中放置“ dist”内容,然后在UI中输入Web服务http://localhost:8080/Webservice/api-doc.json
,例如: 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
软件包的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。
如果您使用的是JAX-RS和Maven,则也可以考虑尝试MireDot ,它的设置非常容易。
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.