使用Swagger编写Spring REST API文档

Question

我正在寻找一款工具，可以帮助我生成RESTful API文档。我的服务器是使用Java编写的，并使用Spring MVC框架。我的服务器中没有视图，它是一个完全的RESTful服务，其功能就是接收JSON并输出JSON。

我想知道Swagger是否与Spring注释兼容？

- jsf

Answer 1

目前尚未有Spring MVC Swagger模块可用（至少从Wordnik没有），但总体上，在基于JVM的REST服务上启用Swagger相当简单。

Swagger服务器支持分为两部分-核心服务器和与REST服务的集成。请参见Swagger github repo。Swagger核心定义表示REST服务、参数、允许值、HTTP操作等的文档。服务器集成将此文档与REST框架的结构连接起来。Wordnik使用JAX-RS的Jersey并发布swagger-jaxrs来执行此集成。还有一个Swagger-Play模块，即将发布到Play模块存储库中。

如果要在其他REST框架（如Spring MVC）上启用Swagger，则应按照以下步骤操作：

1）生成API Reader以生成com.wordnik.swagger.core.Documentation对象。请参见JAX-RS版本以及play版本。

2）创建一个REST端点，该端点向客户端返回Documentation对象的JSON/XML版本。同样，JAX-RS和play也有实现。

3）添加一个过滤器来拦截请求以执行资源或对象级别的访问控制。

因此，总之，这可以相当容易地组合在一起。

- fehguy

---

能否创建一个纯Java模块？ - tbruyelle

现有一个用于Swagger的SpringMVC模块，位于此处：https://github.com/martypitt/swagger-springmvc。 - Marty Pitt

请问您能提交Swagger标签吗？请参考这里：http://stackoverflow.com/documentation/swagger/commit - Stephan

Answer 2

这里正在进行Swagger-SpringMVC的实现，这里有实现代码，这里有示例。

规范v1.2已完全实现并受到支持（即生成了模型，并完全支持泛型），目前仍在积极开发中。

- Marty Pitt

---

几年过去了。你列出的示例项目正在使用Swagger 0.7.0（当前版本为0.8.3）。你能确认一下这个示例项目仍然相关吗？我在配置我的项目时遇到了麻烦。 - stephen.hanson

@steve.hanson 0.8.4已发布，ReadMe中的示例演示链接已更新。此外，配置已大大简化。 - Dilip Krishnan

Answer 3

另一种Spring MVC的Swagger实现是swagger4spring-web。

它类似于Swagger-SpringMVC，支持所有Swagger注解，并为返回类型和参数生成JSON schema。它也可以在没有Swagger注解的情况下工作。

- Waggins

Answer 4

Swagger 2.0 是最新的 Swagger 版本。

现在有不同版本的 Swagger 可供不同需求使用。

io.swagger 是 Swagger 库的包，您需要单独的 Spring JAR 包来与 Spring 配合使用。这是 Swagger 的第二个版本。

io.springfox 是 Springfox Swagger2，其中 swagger 已经与 Spring 集成。

com.mangofactory 是与 Spring Web MVC 框架集成的 swagger。

- Sampada

Answer 5

如果您只需要生成一个交互式API文档（不需要维基风格的协作），I/O Docs将是更好的解决方案，它需要更少的设置、使用和自定义工作量，就我个人而言。

它运行在nodejs和Redis上。您只需要编写API的JSON模式，它就会生成一个HTML/JS网站，描述您的API，并允许开发人员直接从浏览器中实时测试。

我计划将我的API托管在我的服务器上（因为要求任何人安装其他2个软件来查看API太疯狂了），但JSON模式本身已经具有良好的可读性和紧凑的结构，我认为这足以与其他程序员进行协作。这是一个小项目。

您可能想要查看类似的问题。

- Mzq