目前，在微服务项目开发过程中基本采用的都是前后端分离模式。如果前后端多人开发同一个项目，那么在系统集成时团队合作使用的联调工具就会对整体项目有重要影响，一个好的工具会对项目的整体开发进度起到促进作用。
通过近两期项目实践，发现两个过程可以优化：
1、对于开发时间要求比较高的项目（比如10天内完成技术文档的编写、前后端代码的开发、联调、测试、部署及上线），此时技术接口文档起到一个前后端开发与联调的桥梁作用，在短时间内形成的技术文档，肯定有考虑不完善的地方，这些瑕疵往往是随着实际代码编写及联调陆续发现的，此时不断更新技术文档的时间成本往往较高，累计起来，对于10天项目周期来说，更新文档的时间大约会占用一天到一天半的时间，也就是整个项目开发时间的10~15%，此过程可以优化。
2、联调阶段，前端通常会用Postman，参考接口技术文档中提供的访问路径，对不同接口输入不同的参数，对比输出结果。在实际过程中经常会调整接口，而接口微调会涉及到前后端接口沟通、技术文档更新工作，联调阶段耗时占整个项目开发时间的30~40%，此过程可以优化。
优化方法如下：
1、写好技术文档初稿后，在搭建初始代码框架时整合Swagger，通过Swagger提供的注解，依据技术文档，将接口信息写入初始代码（此工作会耗时0.5工作日），Swagger会自动生成、带有联调工具的接口文档；在实际后端开发过程中调整接口时，只要微调代码就可以自动生成新的技术接口文档，而前端随时可以在线看到最新的技术文档并进行调试，此过程改进之后，项目进度会加快5~10%。
2、Swagger在同一项目前后端联调时可以替代Postman，前端通过访问swagger-ui.html就可以测试是否能拿到正确的响应数据，联调阶段用Swagger，可以有效加快项目联调进度，相比原来的联调时间，节省20~30%时间。
本文用Springboot说明整合swagger（官网：https://swagger.io，亚马逊、微软、IBM等主流公司都在用swagger），非常简单。
1、在pom依赖中加入对Swagger的支持。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
2、增加Swagger配置
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Value(value = "${swagger.enabled}")
Boolean swaggerEnabled;
@Bean
public Docket createRestApi() {
ParameterBuilder tokenPar = new ParameterBuilder();
List<Parameter> pars = new ArrayList<>();
tokenPar.name("token").description("token").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
pars.add(tokenPar.build());
return new Docket(DocumentationType.SWAGGER_2)
.enable(swaggerEnabled)
.select()
.apis(RequestHandlerSelectors.basePackage("com.china.mobile.coc.compass.treasure.controller"))
.paths(PathSelectors.any())
.build()
.pathMapping("/")
.globalOperationParameters(pars)
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("**中心平台")
.description("测试路径：http://**/compass")
.termsOfServiceUrl("http://**/compass")
.contact("wangjinbo")
.version("1.0")
.build();
}
}
@Configuration
public class WebConfig extends WebMvcConfigurationSupport {
@Override
public void addInterceptors(InterceptorRegistry registry) {
InterceptorRegistration addInterceptor = registry.addInterceptor(getTokenHandlerInterceptor()).addPathPatterns("/**").excludePathPatterns("/swagger-resources/**", "/webjars/**", "/swagger-ui.html/**");
}
@Bean
public TokenHandlerInterceptor getTokenHandlerInterceptor() {
return new TokenHandlerInterceptor();
}
@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/");
}
}
3、在Controller类和入参类的代码中加入Swagger提供的注解，比如：
@GetMapping("/listAll")
@ApiOperation(value="信息全查询", notes="IF13简要信息全查询")
swagger的全部注解使用说明，见官方提供（https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations#quick-annotation-overview）
4、在application配置文件中配置技术文档访问开关
指定只有开发环境才可以访问：swagger.enabled=true
实际效果：在浏览器中输入http://**:8080/compass/swagger-ui.html即可随时访问最新的技术文档啦！_
