Java 使用 swagger 或任何其他工具生成 Rest API 文档
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/19209926/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
Generating Rest API documentation using swagger or any other tool
提问by Erik Sapir
I am looking for a way to document my Rest APIs. My server is a Tomcat/Spring server and the Rest APIs are implemented using Jenkins.
我正在寻找一种方法来记录我的 Rest API。我的服务器是 Tomcat/Spring 服务器，Rest API 是使用 Jenkins 实现的。
Swagger seems to be a pretty cool solution but i can't figure out how i can use it with my code. I am looking for the best way to create the json swagger-ui can read - how i should do that?
Swagger 似乎是一个非常酷的解决方案，但我不知道如何在我的代码中使用它。我正在寻找创建 json swagger-ui 可以读取的最佳方法 - 我应该怎么做？
Also, i would be happy to check any other good solutions for documenting Rest APIs in such environment.
此外，我很乐意检查在这种环境中记录 Rest API 的任何其他好的解决方案。
采纳答案by ragnor
I haven't tried swagger but you may try enunciate. It can generate documentation of JAX-RS endpoints as a part of javadoc phase. Some examples of generated documentation are available on enunciate page
我没有尝试过 swagger 但你可以尝试enunciate。它可以生成 JAX-RS 端点的文档作为 javadoc 阶段的一部分。生成的文档的一些示例可在enunciate 页面上找到
Update
更新
Project has been moved to http://enunciate.webcohesion.com/, java 8 will be supported by upcoming version 2.0.
项目已移至http://enunciate.webcohesion.com/，即将发布的 2.0 版将支持 Java 8。
回答by emgsilva
To enable swagger-ui, you can use it "as-is" - from documentation:
要启用 swagger-ui，您可以“按原样”使用它 - 来自文档：
"You can use the swagger-ui code AS-IS! No need to build or recompile--just clone this repo and use the pre-built files in the dist folder. If you like swagger-ui as-is, stop here."
“您可以按原样使用 swagger-ui 代码！无需构建或重新编译——只需克隆这个 repo 并使用 dist 文件夹中的预构建文件。如果您喜欢 swagger-ui 原样，请到此为止。 ”
So basically you would need only to place the "dist" contents in your web server, then you enter the swagger endpoint of your web service in the UI, for example: http://localhost:8080/Webservice/api-doc.json(this is the same address endpoint you have to define in your web.xml).
所以基本上你只需要在你的 web 服务器中放置“dist”内容，然后你在 UI 中输入你的 web 服务的 swagger 端点，例如：（http://localhost:8080/Webservice/api-doc.json这是你必须在 web.xml 中定义的相同地址端点）。 xml）。
I suspect you have some other details misconfigured, which is easy as there are several places you have to configure Swagger. In the following I give you some details of my own setup in Swagger.
我怀疑您有一些其他细节配置错误，这很容易，因为您必须在多个地方配置 Swagger。下面我将向您介绍我自己在 Swagger 中的设置的一些细节。
This is a snippet of the Swagger configurations on my web.xml:
这是我的 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.Hymanson.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.Hymanson.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 is a listing of the com.mywebservice.utils.swaggerpackage, where there are several resources as presented in the Swagger documentation (which now seems to be different from when I set it up, so here it is the full list of documents):
Bellow 是该com.mywebservice.utils.swagger包的列表，其中有 Swagger 文档中提供的几个资源（现在似乎与我设置它时不同，所以这里是完整的文档列表）：
You can find these files (or examples) in the example project from Swagger: https://github.com/wordnik/swagger-core/tree/master/samples/java-jaxrs, which you should try to use as a "template" to setup your swagger. The one file I had trouble with was the ApiListingResource:
您可以在 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.
哈。
