使用Swagger的Spring REST API文档

Question

我正在寻找一种可以帮助我生成RESTful API文档的工具。我的服务器是用Java编写的，并使用Spring MVC框架。我的服务器中没有VIEWS。它是一个100％RESTful服务，它所做的只是消耗JSON并吐出JSON。

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

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）添加过滤器以拦截请求以强制执行资源或对象级访问。

简而言之，它可以很容易地组合在一起。

Answer 2

正在进行Swagger-SpringMVC实施here和示例here。

规范v1.2已完全实现和支持（即生成模型，完全支持泛型），并且正在积极开发中。

Answer 3

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

它与Swagger-SpringMVC类似，支持所有Swagger注释，并为返回类型和参数生成JSON模式。它也可以在没有招摇的情况下工作。

Answer 4

如果您只是在生成交互式API文档之后（不需要wiki样式协作），I/O Docs将是一个更好的解决方案，需要更少的工作来设置，使用和自定义，恕我直言。

它正在nodejs和Redis上运行。您只需编写API的JSON模式，它就会生成一个描述您的API的HTML / JS网站，并允许开发人员通过浏览器实时播放。

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

您可能需要查看similar question。

Answer 5

Swagger 2.0是Swagger的最新版本。

现在有不同的Swagger变体可用于不同的需求。

io.swagger是swagger库的包，你需要单独的spring jar来将它与Spring结合起来。这是swagger的第2版。

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

com.mangofactory与Spring Web MVC框架非常集成。