强烈推荐一个大神的人工智能的教程：http://www.captainai.net/zhanghan
【前言】
前后端分离是现在系统的主流，前端人员更多专注于前端功能，后端人员更加关注后端极大提高开发效率；一般情况下前后端由不同的开发团队进行开发；所以免不了要有一份接口文档，手写接口文档，维护接口文档团队间沟通，调试等也是需要花费一定的时间，Swagger就在一定程度上解决了以上问题；今天将自己的项目集成Swagger;
【集成Swagger之路】
一、Springboot集成Swagger的方式
1、Pom中增加相关依赖
<!-- swagger --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>${springfox-swagger2.version}</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>${springfox-swagger-ui.version}</version> </dependency>
2、增加Swagger配置类
package com.zhanghan.zhboot.config; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; /** * Swagger2配置类 * 在与spring boot集成时，放在与Application.java同级的目录下。 * 通过@Configuration注解，让Spring来加载该类配置。 * 再通过@EnableSwagger2注解来启用Swagger2。 */ @Configuration @EnableSwagger2 @ConditionalOnProperty(name = "swagger.enable", havingValue = "true") public class SwaggerConfig { //定义扫描的controller的路径 private final static String controllerPath = "com.zhanghan.zhboot.controller"; /** * 创建API应用 * apiInfo() 增加API相关信息 * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现， * 本例采用指定扫描的包路径来定义指定要建立API的目录。 * * @return */ @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage(controllerPath)) .paths(PathSelectors.any()) .build(); } /** * 创建该API的基本信息（这些基本信息会展现在文档页面中） * 访问地址：http://项目实际地址/swagger-ui.html * * @return */ private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("springboot集成swagger") .description("简单优雅的restfun风格，https://blog.csdn.net/zhanghan18333611647") .termsOfServiceUrl("https://blog.csdn.net/zhanghan18333611647") .version("1.0") .build(); } }
3、application中增加Swagger开关（此开关为true则代表启用Swagger;false则不启用Swagger；一般为安全起见生产环境置为false）
#****************************swagger*************************** #true is display swagger; false not disply swagger swagger.enable=true
4、controller中增加相关的Swagger描述
package com.zhanghan.zhboot.controller; import com.mysql.jdbc.StringUtils; import com.zhanghan.zhboot.controller.request.MobileCheckRequest; import com.zhanghan.zhboot.properties.MobilePreFixProperties; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.validation.annotation.Validated; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestMethod; import org.springframework.web.bind.annotation.RestController; import java.util.HashMap; import java.util.Map; @RestController @Api(value = "校验手机号控制器",tags = {"校验手机号控制器"}) public class CheckMobileController { @Autowired private MobilePreFixProperties mobilePreFixProperties; @ApiOperation(value="优雅校验手机号格式方式",tags = {"校验手机号控制器"}) @RequestMapping(value = "/good/check/mobile", method = RequestMethod.POST) public Map goodCheckMobile(@RequestBody @Validated MobileCheckRequest mobileCheckRequest) { String countryCode = mobileCheckRequest.getCountryCode(); String proFix = mobilePreFixProperties.getPrefixs().get(countryCode); if (StringUtils.isNullOrEmpty(proFix)) { return buildFailResponse(); } String mobile = mobileCheckRequest.getMobile(); Boolean isLegal = false; if (mobile.startsWith(proFix)) { isLegal = true; } Map map = new HashMap(); map.put("code", 0); map.put("mobile", mobile); map.put("isLegal", isLegal); map.put("proFix", proFix); return map; } @ApiOperation(value="扩展性差校验手机号格式方式",tags = {"校验手机号控制器"}) @RequestMapping(value = "/bad/check/mobile", method = RequestMethod.POST) public Map badCheckMobile(@RequestBody MobileCheckRequest mobileCheckRequest) { String countryCode = mobileCheckRequest.getCountryCode(); String proFix; if (countryCode.equals("CN")) { proFix = "86"; } else if (countryCode.equals("US")) { proFix = "1"; } else { return buildFailResponse(); } String mobile = mobileCheckRequest.getMobile(); Boolean isLegal = false; if (mobile.startsWith(proFix)) { isLegal = true; } Map map = new HashMap(); map.put("code", 0); map.put("mobile", mobile); map.put("isLegal", isLegal); map.put("proFix", proFix); return map; } private Map buildFailResponse() { Map map = new HashMap(); map.put("code", 1); map.put("mobile", ""); map.put("isLegal", false); map.put("proFix", ""); return map; } }
5、请求实体中增加相关的Swagger描述
package com.zhanghan.zhboot.controller.request; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.Data; import javax.validation.constraints.NotNull; @ApiModel("手机号校验请求实体") @Data public class MobileCheckRequest { @ApiModelProperty(value = "国家编码",required = true) @NotNull private String countryCode; @ApiModelProperty(value = "手机号",required = true) @NotNull private String mobile; }
二、效果展示
1、启动项目访问地址：http://localhost:8080/swagger-ui.html
2、Try it out
3、Execute
三、项目地址及代码版本：
1、地址：GitHub - dangnianchuntian/springboot: springboot
2、代码版本：1.1.0-Release
【总结】
1、充分利用好工具提高效率；
2、小工具有大用处，多去研究。
