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>