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>