Swagger

• Restful API 文档在线自动生成工具;API文档与API定义同步更新
• 直接运行,可以在线测试API接口,接口文档实时更新
• 支持多种语言
• 可以通过Swagger给一些比较难理解的属性或接口增加注释信息

官网

使用

项目使用需要springbox;

• swagger2
• ui

Spring Boot继承Swagger

以下内容代码存放在码云仓库

代码链接

新建SpringBoot-Web项目

导入相关依赖

// https://mvnrepository.com/artifact/io.springfox/springfox-swagger2
implementation group: 'io.springfox', name: 'springfox-swagger2', version: '2.10.5'// https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui
implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.10.5'

// 此次使用的swagger 2.10.5版本,此版本删除了配置文件的@EnableSwagger2注解,需要用@EnableSwagger2WebFlux或者@EnableSwagger2WebMvc注解,故需要导入三个依赖,以下依赖二选一即可// 1 使用@EnableSwagger2WebFlux注解// https://mvnrepository.com/artifact/io.springfox/springfox-spring-webflux
implementation group: 'io.springfox', name: 'springfox-spring-webflux', version: '2.10.5'// 2  使用@EnableSwagger2WebMvc注解// https://mvnrepository.com/artifact/io.springfox/springfox-spring-webmvc
implementation group: 'io.springfox', name: 'springfox-spring-webmvc', version: '2.10.5'

编写工程代码,开启Swagger

@Configuration
// @EnableSwagger2WebFlux          //开启Swagger2WebFlux
@EnableSwagger2WebMvc          //开启Swagger2WebMvc
public class SwaggerConfig {
}

配置好以上内容,可以启动程序进行测试,

http://ip:port/swagger-ui.html

效果图如下:

配置Swagger

Swagger的bean实例Docket;

1. 配置Swagger信息:Docket.apiInfo()

   @Configuration
   // @EnableSwagger2WebFlux          //开启Swagger2WebFlux
   @EnableSwagger2WebMvc          //开启Swagger2WebMvc
   public class SwaggerConfig {/*** @ClassName SwaggerConfig* @Description     配置Swagger的Docket的bean实例* @Author admin* @Date 2020/7/6 20:54* @Version 1.0*/@Beanpublic Docket docket(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());}/*** @Author admin* @Description 配置Swagger信息* @Date 20:55 2020/7/6* @return**/private ApiInfo apiInfo(){// 作者信息Contact DEFAULT_CONTACT = new Contact("hanson", "http://localhost:8080", "邮箱");// 没有set方法,只能通过构造器设置值return new ApiInfo("Hello API文档","心有猛虎,细嗅蔷薇","V1.0","http://localhost:8080",DEFAULT_CONTACT,"Apache 2.0","http://www.apache.org/licenses/LICENSE-2.0",new ArrayList<>());}
   }
   

   效果图:

   

2. 配置Swagger扫描接口:Docket.select()

   @Bean
   public Docket docket(){return new Docket(DocumentationType.SWAGGER_2)// 配置作者信息.apiInfo(apiInfo())//配置扫描接口.select()// RequestHandlerSelectors 配置扫描接口方式// basePackage 指定要扫描的包// any() 扫描全部// none() 都不扫描// withClassAnnotation() 扫描类上的注解,需要是一个注解的反射对象// withMethodAnnotation() 扫描方法上的注解.apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))// 路径过滤// ant() 过滤指定路径// any() 全部过滤// none() 都不过滤// regex() 正则匹配过滤.paths(PathSelectors.ant("*/service/*")).build();
   }
   

3. 配置是否启动Swagger

   @Bean
   public Docket docket(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())//配置是否开启Swagger,true开启,false关闭.enable(true).select().apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller")).build();
   }
   

配置API文档分组

@Bean
public Docket docket(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(true)// 配置API文档分组.groupName("hanson").select().apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller")).build();
}

配置多个分组:配置多个Swagger的bean实例Docket

@Bean
public Docket docket2(){return new Docket(DocumentationType.SWAGGER_2).groupName("hanson2");
}
@Bean
public Docket docket3(){return new Docket(DocumentationType.SWAGGER_2).groupName("hanson3");
}
@Bean
public Docket docket4(){return new Docket(DocumentationType.SWAGGER_2).groupName("hanson4");
}

实体类配置

// 1 在接口中返回值中存在实体类,就会扫描到swagger
@GetMapping(value = "/user")
public User usr(){return new User();
}
// 给实体类添加注解 @ApiModel("用户实体类")
// 也可以给字段添加注解 @ApiModelProperty("用户名")
@ApiModel("用户实体类")
public class User {@ApiModelProperty("用户名")public String username;public int age;
}

给方法加注释:@ApiOperation(“用户方法注释”)

@ApiOperation("用户方法注释")
@GetMapping(value = "/user")
public User usr(){return new User();
}