【发布时间】：2012-02-08 05:49:27
【问题描述】：
我正在寻找可以帮助我生成 RESTful API 文档的工具。我的服务器是用 Java 编写的，并使用 Spring MVC 框架。我的服务器中没有 VIEWS。这是一个 100% 的 RESTful 服务，它所做的只是消耗 JSON 并输出 JSON。
我想知道Swagger是否与Spring注解兼容？
【问题讨论】：
标签： spring api rest documentation swagger
【发布时间】：2012-02-08 05:49:27
【问题描述】：
目前没有可用的 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 端点，它将文档对象的 JSON/XML 版本返回给客户端。同样，JAX-RS 和 play。
3) 添加过滤器来拦截请求以强制资源或对象级访问。
简而言之，它可以很容易地组合在一起。
【讨论】：
-
是否可以创建一个纯 java 的模块？
-
Swagger 的 SpringMVC 模块现在存在于此处：github.com/martypitt/swagger-springmvc
-
你能提交swagger标签吗？见这里：stackoverflow.com/documentation/swagger/commit
Spring MVC 的 Swagger 的另一个实现是 swagger4spring-web。
它类似于 Swagger-SpringMVC，支持所有 Swagger 注解，并为返回类型和参数生成 JSON 模式。它也可以在没有大张旗鼓的注释的情况下工作。
【讨论】：
如果您只是在生成交互式 API 文档（不需要 wiki 样式协作）之后，I/O Docs 将是一个更好的解决方案，需要更少的工作量来设置、使用和自定义，恕我直言。
它在 nodejs 和 Redis 上运行。您只需要编写 API 的 JSON 模式，它会生成一个 HTML/JS 站点来描述您的 API，并让开发人员可以通过浏览器实时使用它。
我计划在我的服务器上托管我的 API（因为要求任何人安装 2 个其他软件只是为了查看 API 会很疯狂）但是 JSON 模式本身已经具有很好的可读性和紧凑的结构，我认为这足以满足与其他程序员合作。这是一个小项目。
您可能想查看similar question。
【讨论】：
Swagger 2.0 是 Swagger 的最新版本。
现在有不同的 Swagger 变体可以满足不同的需求。
io.swagger 是 swagger 库的包，你需要单独的 spring jar 来将它与 Spring 耦合。这是 swagger 的第 2 版。
io.springfox 是 Springfox Swagger2，其中 swagger 与 Spring 集成。
com.mangofactory swagger 与 Spring Web MVC 框架集成。
【讨论】：