Spring REST实践之Documenting REST Services

Swagger基本介绍

Swagger是创建交互式REST API文档的规范和框架，它能自动同步REST服务的任何变化，同时为生成API客户端代码提供了一套工具和SDK生成器。Swagger规范由两种文件类型组成：资源文件（包含一系列文件）和一套API声明文件（描述了REST API和可用的操作）。资源文件是API声明文件的根，它描述了一般信息，比如API版本、title、描述、license，同时它也包含了所有可用的API资源。API声明文件描述了带有API操作和请求/响应展现的资源，basePath域提供了API的根URI，resourcePath指定了相对于basePath的资源路径，apis域包含了描述API操作的接口对象，models域包含了和资源相关的模型对象。

Swagger使用JSON作为描述语言。

集成Swagger

在POM文件中加入如下依赖：

<dependency>

	<groupId>com.mangofactory</groupId>

	<artifactId>swagger-springmvc</artifactId>

	<version>1.0.2</version>

</dependency>

然后通过@EnableSwagger注解激活swagger-springmvc。

Swagger UI

Swagger UI是Swagger的一个子项目，能够利用资源文件和API描述文件为API自动生成友好的、可交互的接口。

在应用中集成Swagger UI的方法是：首先从https://github.com/swagger-api/swagger-ui下载Swagger UI的稳定版本，然后dist文件夹下的内容移动到应用的类路径下（一般放到resoures目录下）。更改index.html文件中的如下内容

$(function () {

	window.swaggerUi = new SwaggerUi({

	url: "http://localhost:8080/api-docs",

	dom_id: "swagger-ui-container",

	// code removed for brevity

}

最后通过http://localhost:8080/swagger-ui/index.html启动Swagger UI。

定制Swagger

可通过在应用中建立一个配置类实现对Swagger的定制。

import javax.inject.Inject;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import com.mangofactory.swagger.configuration.SpringSwaggerConfig;

import com.mangofactory.swagger.models.dto.ApiInfo;

import com.mangofactory.swagger.models.dto.builder.ApiInfoBuilder;

import com.mangofactory.swagger.plugin.EnableSwagger;

import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;

@Configuration

@EnableSwagger

public class SwaggerConfig {

	@Inject

	private SpringSwaggerConfig springSwaggerConfig;

	private ApiInfo getApiInfo() {

		ApiInfo apiInfo = new ApiInfoBuilder()

				        .title("QuickPoll REST API")

				        .description("QuickPoll Api for creating and managing polls")

				        .termsOfServiceUrl("http://example.com/terms-of-service")

				        .contact("info@example.com")

				        .license("MIT License")

				        .licenseUrl("http://opensource.org/licenses/MIT")

				        .build();

		return apiInfo;

	}

	@Bean

	public SwaggerSpringMvcPlugin v1APIConfiguration() {

		SwaggerSpringMvcPlugin swaggerSpringMvcPlugin = new SwaggerSpringMvcPlugin(this.springSwaggerConfig);

		swaggerSpringMvcPlugin

					.apiInfo(getApiInfo()).apiVersion("1.0")

					.includePatterns("/v1/*.*").swaggerGroup("v1");

		swaggerSpringMvcPlugin.useDefaultResponseMessages(false);

	    	return swaggerSpringMvcPlugin;

	}

}

配置控制器

@API注解标注一个类为Swagger资源，Swagger会扫描标注了 @API的类，读取metadata生成资源文件和API描述文件。

@RestController

@Api(value = "polls", description = "Poll API")

public class PollController {

	// Implementation removed for brevity

}

@ApiOperation注解用于标注API，可以自定义操作信息，比如名字、描述、响应。

@RequestMapping(value="/polls", method=RequestMethod.POST)

@ApiOperation(value = "API概要描述", notes="详细描述信息", response = Void.class)

public ResponseEntity<Void> createPoll(@Valid @RequestBody Poll poll) {

	.......

}

@ApiResponse注解用于配置状态码和相关响应body。

RequestMapping(value="/polls", method=RequestMethod.POST)

@ApiOperation(value = "API概要描述", notes="详细描述信息", response = Void.class)

@ApiResponses(value = {@ApiResponse(code=201, message="Poll Created Successfully", response=Void.class),

			@ApiResponse(code=500, message="Error creating Poll", response=ErrorDetail.class) } )

public ResponseEntity<Void> createPoll(@Valid @RequestBody Poll poll) {

	// Content removed for brevity

}

配置UI

更改swagger-ui-wrap内容，将相关信息更改为应用相关的信息，如下所示：

<a id="logo" href="http://localhost:8080">QuickPoll</a>

<form id='api_selector'>

	<div class='input'><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text"/></div>

	<div class='input'><input placeholder="api_key" id="input_apiKey" name="apiKey" type="text"/></div>

	<div class='input'><a id="explore" href="#">Explore</a></div>

</form>

巴特西