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

问题描述

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

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.

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

I was wondering if Swagger is compatible with Spring annotations?

推荐答案

目前没有可用的 Spring MVC swagger 模块(至少来自 Wordnik)，但总的来说，在基于 JVM 的 REST 服务上启用 swagger 非常简单.

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 服务器支持分为两部分——核心服务器和与 REST 服务的集成.请参阅 Swagger github 存储库.Swagger 核心定义了表示 REST 服务、参数、允许值、HTTP 操作等的文档.服务器集成将此文档连接到 REST 框架的结构.Wordnik 通过 JAX-RS 使用 Jersey 并发布了 swagger-jaxrs 来完成此集成.还有一个 Swagger-Play 模块很快发布到 Play 模块存储库.

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.

如果您想在另一个 REST 框架(如 Spring MVC)上启用 swagger，请按照以下步骤操作:

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

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

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) 创建一个 REST 端点，该端点将文档对象的 JSON/XML 版本返回给客户端.同样，JAX-RS 和 播放.

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

3) 添加过滤器以拦截请求以强制执行资源或对象级访问.

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屋！