使用 Swagger 的 Spring REST API 文档
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/9188425/
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
Spring REST API Documentation using Swagger
提问by jsf
I am looking for a tool which could help me generate RESTful API documentation. My server is written in Java and uses Spring MVC framework. I do not have VIEWS in my server. It's a 100% RESTful service and all it does is consumes JSON and spits out JSON.
我正在寻找一种可以帮助我生成 RESTful API 文档的工具。我的服务器是用 Java 编写的，并使用 Spring MVC 框架。我的服务器中没有 VIEWS。这是一个 100% RESTful 服务，它所做的只是消耗 JSON 并输出 JSON。
I was wondering if Swaggeris compatible with Spring annotations?
我想知道Swagger是否与 Spring 注释兼容？
回答by fehguy
There currently is not a Spring MVC swagger module available (from Wordnik at least) but in general, enabling swagger on a JVM-based REST service is pretty simple.
目前没有可用的 Spring MVC swagger 模块（至少来自 Wordnik），但总的来说，在基于 JVM 的 REST 服务上启用 swagger 非常简单。
Swagger server support is divided into two parts--the core server and the integration with the REST service. See the Swagger github repo. Swagger core defines the document that represents the REST service, parameters, allowable values, HTTP operations, etc. The server integration wires this document to the structure of the REST framework. Wordnik uses Jersey via JAX-RS and released swagger-jaxrs to do this integration. There is also a Swagger-Playmodule which will be released to the Play module repository shortly.
Swagger 服务器支持分为两部分——核心服务器和与 REST 服务的集成。请参阅Swagger github 存储库。Swagger 核心定义了表示 REST 服务、参数、允许值、HTTP 操作等的文档。服务器集成将此文档连接到 REST 框架的结构。Wordnik 通过 JAX-RS 使用 Jersey 并发布了 swagger-jaxrs 来完成此集成。还有一个Swagger-Play模块，它将很快发布到 Play 模块存储库。
If you want to enable swagger on another REST framework (like Spring MVC), you follow these steps:
如果要在另一个 REST 框架（如 Spring MVC）上启用 swagger，请按照以下步骤操作：
1) Generate an API Reader to generate a com.wordnik.swagger.core.Documentation object. See the JAX-RSversion as well as the one for play.
1) 生成 API Reader 以生成 com.wordnik.swagger.core.Documentation 对象。请参阅JAX-RS版本以及用于播放的版本。
2) Create a REST endpoint which returns a JSON/XML version of the Documentation object to the client. Again, JAX-RSand play.
2) 创建一个 REST 端点，它将文档对象的 JSON/XML 版本返回给客户端。再次，JAX-RS并播放.
3) Add a filter to intercept requests to enforce resource or object-level access.
3) 添加过滤器来拦截请求以强制执行资源或对象级访问。
So in short, it could be put together pretty easily.
简而言之，它可以很容易地组合在一起。
回答by Marty Pitt
回答by Waggins
Another implementation of Swagger for Spring MVC is swagger4spring-web.
Spring MVC 的 Swagger 的另一个实现是swagger4spring-web。
It's similar to Swagger-SpringMVC and supports all Swagger annotations and generates JSON schema for return types and parameters. It also works without swagger annotations.
它类似于 Swagger-SpringMVC，支持所有 Swagger 注解，并为返回类型和参数生成 JSON 模式。它也可以在没有 swagger 注释的情况下工作。
回答by Sampada
Swagger 2.0is the latest version of Swagger.
Swagger 2.0是Swagger的最新版本。
There are different variations of Swagger now available for differing needs.
现在有不同的 Swagger 变体可用于满足不同的需求。
io.swaggeris the package for swagger libraries and you need separate spring jars to couple it with Spring. This is version 2 of swagger.
io.swagger是 swagger 库的包，您需要单独的 spring jars 将它与 Spring 耦合。这是 swagger 的第 2 版。
io.springfoxis Springfox Swagger2, wherein swagger comes integrated with Spring.
io.springfox是 Springfox Swagger2，其中 swagger 与 Spring 集成在一起。
com.mangofactoryis swagger integrated with Spring Web MVC framework.
com.mangofactoryswagger 与 Spring Web MVC 框架集成。
回答by Miranda
If you are only after generating an interactive API document (without the need for wiki style collaboration), I/O Docswould be a better solution requires much less effort to set up, use and customise, IMHO.
如果您只是在生成交互式 API 文档（不需要 wiki 风格的协作）之后，I/O Docs将是一个更好的解决方案，需要更少的精力来设置、使用和定制，恕我直言。
It's running on nodejs and Redis. You only need to write a JSON schema of your API and it generates a HTML/JS site that describes your API and lets developers to play with it live from their browser.
它在 nodejs 和 Redis 上运行。您只需要编写 API 的 JSON 模式，它就会生成一个 HTML/JS 站点来描述您的 API，并让开发人员可以在他们的浏览器中实时使用它。
I plan to host my API on my server (as requiring anyone to install 2 other softwares just to view the API would be crazy) but the JSON schema itself already has a nice readable and compact structure which I think would be sufficient for collaboration with other programmers. It's a small project.
我计划在我的服务器上托管我的 API（因为要求任何人安装 2 个其他软件只是为了查看 API 会很疯狂）但是 JSON 模式本身已经有一个很好的可读和紧凑的结构，我认为这足以与其他人协作程序员。这是一个小项目。
There is a similar questionyou may want to check out.
您可能想查看一个类似的问题。
