API管理-基于SpringBoot项目集成swagger实现接口文档自动生成

1. 为什么要使用swagger？

上一次博客（API管理-使用开源xxl-api项目管理接口）中我也提到过接口文档在整个生命周期中的重要性以及使用开源xxl-api的优缺点，缺点就是没法自动完成接口文档的生成，而是手动的录入，这样的话跟我们传统的通过编写word来管理接口文档也没什么区别；而swagger却是通过开发者在编写接口的时候就已经通过指定的注解标注好接口的信息，在启动的时候swagger会自动生成对应的接口文档。

2. SpringBoot配置使用方式

• 配置pom.xml依赖

<!-- swagger2 -->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
   <!--  <version>2.8.0</version> -->
</dependency>

<!-- springfox-swagger原生ui  -->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.9.2</version>
</dependency>

• 配置SwaggerConfig类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
	
	@Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.api.rest.controller"))
                .paths(PathSelectors.any())
                .build();
//                .build().enable(false); // 线上关闭接口
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("智慧卫检-监督员系统")
                .description("监管系统")
                .termsOfServiceUrl("http://www.zhihuiweijian.com/")
                //.contact(contact)
                .version("1.0")
                .build();
    }

}

• 配置MvcConfig类

@Configuration
public class MvcConfig extends WebMvcConfigurationSupport {

	/**
	*
	* 功能描述:
	*  配置静态资源,避免静态资源请求被拦截
	* @auther: Tt(yehuawei)
	* @date:
	* @param:
	* @return:
	*/
	public void addResourceHandlers(ResourceHandlerRegistry registry) {
	   //如果静态文件放到了classpath 下，就如下配置。
	   registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");

	   /*放行swagger*/
	   registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
	   registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
	   super.addResourceHandlers(registry);
	}
}

• 以规定的注解编写接口信息

@ApiOperation(value="账号密码登录", notes="账号密码登录")
@ApiImplicitParams({
	@ApiImplicitParam(name = "mobile", value = "账号", required = true, dataType = "String"),
	@ApiImplicitParam(name = "password", value = "密码", required = true, dataType = "String")
})
@RequestMapping(value="accountLogin")
public ApiCommonResultVo login(String mobile, String password) {}

• 启动项目、访问地址、查看接口信息：http://localhost:8080/swagger-ui.html
• 效果图

3. 总结

Swagger API 接口文档生成工具的利与弊，对于使用swagger利弊这边文章已经解释的很清楚了，虽然通过这种方式集成swagger后有一个统一的接口可以查看接口信息了，但这个springfox-swagger-ui版本的并不支持接口文档的下载以便于离线查看，还有就是原生的ui使用起来总感觉不顺手，所以又有人基于swagger的接口方式自定义开发了基于bootstrap的ui并扩展了部分功能，详细请参考博客：API管理-舍弃springfox-swagger-ui，采用功能更加丰富的swagger-bootstrap-ui。