使用Swagger的Spring REST API文档 [英] Spring REST API Documentation using Swagger

问题描述

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

我想知道如果 Swagger 与Spring注释兼容？

解决方案

目前没有一个Spring MVC swagger模块可用（至少从Wordnik），但一般来说，在基于JVM的REST服务上启用swagger相当简单。

Swagger服务器支持分为两部分 - 核心服务器和与REST服务的集成。请参阅 Swagger github repo 。 Swagger核心定义表示REST服务，参数，允许值，HTTP操作等的文档。服务器集成将此文档连接到REST框架的结构。 Wordnik通过JAX-RS使用泽西，并发布swagger-jaxrs来进行这种集成。还有一个 Swagger-Play 模块，将会是如果要在其他REST框架（如Spring MVC）上启用swagger，请按照下列步骤操作：

1）生成API Reader以生成一个com.wordnik.swagger.core.Documentation对象。请参阅 JAX-RS 版本以及播放。

2）创建返回JSON / XML版本的REST端点的文档对象发送给客户端。再次， JAX-RS 和 play 。

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

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

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.

I was wondering if Swagger is compatible with Spring annotations?

解决方案

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.

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-Play module which will be released to the Play module repository shortly.

If you want to enable swagger on another REST framework (like Spring MVC), you follow these steps:

1) Generate an API Reader to generate a com.wordnik.swagger.core.Documentation object. See the JAX-RS version as well as the one for play.

2) Create a REST endpoint which returns a JSON/XML version of the Documentation object to the client. Again, JAX-RS and play.

3) Add a filter to intercept requests to enforce resource or object-level access.

So in short, it could be put together pretty easily.

这篇关于使用Swagger的Spring REST API文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！