swagger集成springboot，（一篇让你瞬间精通swagger2.9.2的文章）
一，导入相关依赖
maven下载：springfox.swagger2，springfox.swaggerUI
或者在springboot项目中，直接导入一个依赖springfox-boot-starter（目前最新版本3.0.0）
<!--swagger--> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
注意：这里我用到时swagger2.9.2版本，建议使用swagger3.0.0的
swagger3.0.0是当前最新版本，它简化了swagger2.9.2的部分操作，如号称“零配置”，那么问题来了，博主为什么没有直接学swagger3呢？
因为swagger3目前还是有一些不足的，且博主能力有限，不能够直接看源码就能学懂，所以我选择学swagger2（网上教学ziyuanduo），
还有一个就是swagger2和3其实也没差多少，博主打算swagger3更稳定的时候在看一遍就行了hhhhh
二，配值swagger，（编写配置类）
1.集成springboot（没有自定义，那么都走默认的）
@Configuration @EnableSwagger2 //开启swagger2 public class SwaggerConfig { }
2.测试：请求http://localhost:8080/swagger-ui.html
2.配置swagger的docket的bean实例对象docket（核心时文档插件）
2.1，docket的bean实例来源核心
2.2Swagger的接口初始化配置
Docket.apiInfo()
@Configuration @EnableSwagger2 //开启swagger2 public class SwaggerConfig { //配置Swagger的Docket的bean实例 @Bean public Docket docket(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()); } private ApiInfo apiInfo(){ //存放作者信息 Contact contact = new Contact("king", "https://www.cnblogs.com/CL-King/", "3342239623@qq.com"); return new ApiInfo( "king的Swagger API文档", "测试！测试！", "1.0", "https://www.cnblogs.com/CL-King/", contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList()); } }
2.3，Swagger配置扫描接口
Docket.select()
@Bean public Docket docket(){ return new Docket(DocumentationType.SWAGGER_2) //requestHandlerSelector配置要扫描接口的方式 .apis(RequestHandlerSelectors.basePackage("com.king.swagger.controller"))//basePackage基于某个包去扫描 .build(); }
2.4,过滤什么路径
Docket.paths()
@Bean public Docket docket(){ return new Docket(DocumentationType.SWAGGER_2)//paths()过滤什么路径,只扫描自定义路径的接口 .paths(PathSelectors.ant("/user/**")) .build(); }
2.5，自动启动swagger
Docket.enable(),默认时true
2.6，Swagger的常用完整配置
补充：分组，Docket.groupName("name")
实现多个分组：注册多个bean就可以了
Swagger的常用完整配置
//配置Swagger的Docket的bean实例 @Bean public Docket docket(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .enable(false)//enab是否启动Swagger，默认true .select() //requestHandlerSelector配置要扫描接口的方式 .apis(RequestHandlerSelectors.basePackage("com.king.swagger.controller"))//basePackage基于某个包去扫描 //paths()过滤什么路径,只扫描自定义路径的接口 /*.paths(PathSelectors.ant("/user/**"))*/ .build(); }
问题：如何让swagger在开发环境中启用，在上线环境下关闭？
思路：多环境配置，（一个开发环境dev，一个发布环境pro），
通过判断所处环境，给Docket.enable()赋值；
扩展：因为enable要的时boolean值，
方法一：所以可以才环境配置文件中写死，在swagger配置类中获取最后传给Docket.enable（）
方法二：也可以通过子swagger类中写死开启swagger的环境的方式来实现
实现写的是方法二的代码，方法一简单就不去写了
实现：
//配置Swagger的Docket的bean实例 @Bean public Docket docket(Environment environment){ //设置要开启swagger的环境 Profiles profiles = Profiles.of("dev", "test"); //通过environment.acceptsProfiles（）方法判断是否处于设定环境 boolean b = environment.acceptsProfiles(profiles); return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .enable(b)//enab是否启动Swagger，默认true .select() //requestHandlerSelector配置要扫描接口的方式 .apis(RequestHandlerSelectors.basePackage("com.king.swagger.controller"))//basePackage基于某个包去扫描 //paths()过滤什么路径,只扫描自定义路径的接口 /*.paths(PathSelectors.ant("/user/**"))*/ .build(); }
3，实体类配置（待更）
问题：swagger如何与实体类建立关联
解答：在controller层，放回的值只要包含实体类，swagger就会检测到该实体类
//只要接口的返回值中存在实体类，该实体类就会被swagger扫描到 @GetMapping(value = "/user") public User user(){ return new User(); }
swagger关于实体类的注解：
@ApiModel：给实体类加注释通过Swagger，作用在类上
@ApiModelProperty：给实体类的字段加注释通过Swagger，作用在字段上
//给实体类加注释通过Swagger，作用在类上 @ApiModel("用户实体类") public class User { //给实体类的字段加注释通过Swagger，作用在字段上 @ApiModelProperty("用户名") public String username; @ApiModelProperty("密码") public String password; }
问题：细心的同学会发现，我的实体类demo的字段属性是public当改成private后，swagger就检测不到了，怎么办？
解答：很简单，通过相对应的get方式就可以啦，有这个问题的建议去看javase基础，这是类字段属性访问权限问题，这里写public是为了方便测试
swagger关于controller层的注解：
@ApiOperation（”xx“）作用子在方法上
@ApiParam("xx")作用方法传参位置
//@ApiOperation作用子在方法上 @ApiOperation("Hello控制类") @GetMapping(value = "/hello2") public String hello2(@ApiParam("用户名") String username){ return "hello"+username; }
扩展：接口测试
1.找到要测试接口（请求），点击try it out
输入测试参数后，点击Execute
swagger优点：
1.通过swagger给项目中难理解的属性和接口加注解，方便接口测试的可读性，提高效率
2.接口文档实时更新
3.可以在线测试
Swagger是一个非常优秀的框架，几乎所有成规模的公司都会使用它
注意：为确保项目安全，s项目正式发布是要关闭swagger，也节省运行内存
