使用Swagger自動生成API文檔，不僅增加了項目的可維護性，還提高了API的透明度更利於快速測試等工作，便於更快地發現和解決問題。

本篇文章只記錄整合過程，關於Security Configuration等其他特性這裏就不展開講了，感興趣的可以通過以下鏈接了解更多。

參考文檔：

https://howtodoinjava.com/swagger2/swagger-spring-mvc-rest-example/
http://www.baeldung.com/swagger-2-documentation-for-spring-rest-api
http://blog.didispace.com/springbootswagger2/
 

項目中各組件的版本情況：

spring.version=4.3.18.RELEASE
jackson.version=2.9.0
swagger.version=2.7.0

核心的pom配置（spring的省略）：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency
 
>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId
 
>jackson-databind</artifactId>
    <version>${jackson.version}</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-core</artifactId>
    <version>${jackson.version}</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-annotations</artifactId>
    <version>${jackson.version}</version>
</dependency>

編寫Swagger的配置類：

tip：做了攔截處理的同學需要註意開放swagger的資源訪問路徑：/swagger-resources/*、/swagger-ui.html、/v2/api-docs、/webjars/*

@Configuration
@EnableSwagger2
@EnableWebMvc
@ComponentScan("springfox")
public class SwaggerConfig extends WebMvcConfigurerAdapter {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("REST API 描述文檔")
                .description("REST API 描述文檔")
                .version("1.0")
                .termsOfServiceUrl("http://localhost:9080/")
                .contact(new Contact("lichmama", "", ""))
                .license("Apache License 2.0")
                .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
                .build();
    }
    
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

在springmvc-servlet.xml中增加配置：

<bean class="com.lichmama.demo.core.swagger.SwaggerConfig" />

在RestController上使用Swagger的註解（其中ApiOperation和ApiImplicitParam尤為關鍵），用以自動生成文檔：

@RestController
@RequestMapping("/config")
@Api(description = "配置管理接口")
@Slf4j
public class ConfigAction {

    @PostMapping("/set")
    @ApiOperation(value = "更改或新增配置信息")
    @ApiResponses(value = { @ApiResponse(code = 500, message = "系統錯誤"), @ApiResponse(code = 0, message = "成功") })
    @ApiImplicitParams({ @ApiImplicitParam(name = "key", value = "鍵", paramType = "form", dataType = "string"),
            @ApiImplicitParam(name = "value", value = "值", paramType = "form", dataType = "string") })
    public ActionMessage setConfig(String key, String value) {
        log.debug("key: {}, value: {}", key, value);
        ConfigUtil.setConfig(key, value);
        return ActionStatus.success();
    }

    @GetMapping("/get")
    @ApiOperation(value = "獲取配置信息")
    @ApiImplicitParam(name = "key", value = "鍵", paramType = "query", dataType = "string")
    public Map<String, Object> getConfig(String key) {
        Object value = ConfigUtil.getConfig(key);
        log.debug("key: {}, value: {}", key, value);
        Map<String, Object> map = new HashMap<>();
        map.put(key, value);
        return map;
    }
}

啟動項目，訪問http://{host:port}/{project}/swagger-ui.html查看配置是否生效：

看上去沒有問題，測試下：

ps：網上關於swagger的文章配置上多數都有些問題，所以不能直接照搬使用。自己部署swagger時要根據實際項目來修改配置，比如spring、swagger的版本等。

使用Swagger2構建SpringMVC項目中的Restful API文檔