使用Swagger2构建SpringMVC项目中的Restful API文档

使用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的版本等。