一、Swagger简介
1、Swagger简介
Swagger是一套围绕Open API规范构建的开源工具，可以帮助设计，构建，记录和使用REST API。
Swagger工具包括的组件：
Swagger Editor ：基于浏览器编辑器，可以在里面编写Open API规范。类似Markdown具有实时预览描述文件的功能。
Swagger UI：将Open API规范呈现为交互式API文档。用可视化UI展示描述文件。
Swagger Codegen：将OpenAPI规范生成为服务器存根和客户端库。通过Swagger Codegen可以将描述文件生成html格式和cwiki形式的接口文档，同时也可以生成多种言语的客户端和服务端代码。
Swagger Inspector：和Swagger UI有点类似，但是可以返回更多信息，也会保存请求的实际参数数据。
Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。
使用Swagger，就是把相关的信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。
2、官网
https://swagger.io/
3、项目代码
https://download.csdn.net/download/weixin_44624117/85357475
4、参考视频
https://www.bilibili.com/video/BV1yi4y1F7KP
https://download.csdn.net/download/weixin_44624117/85374341
二、初始化Swagger项目
1、pom文件
SpringBoot集成Swagger => springfox，两个jar包
- Springfox-swagger2
- swagger-springmvc
<!--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>
2、Swagger配置类
package com.lydms.swaggerdemo.config; import org.springframework.context.annotation.Configuration; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class SwaggerConfig { }
或者在启动类上加上@EnableSwagger2(效果相同)：
会扫表当前类所在包，以及子包中所有类型的注解。
package com.lydms.swaggerdemo; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import springfox.documentation.swagger2.annotations.EnableSwagger2; @EnableSwagger2 @SpringBootApplication public class SwaggerDemoApplication { public static void main(String[] args) { SpringApplication.run(SwaggerDemoApplication.class, args); } }
3、Controller接口
package com.lydms.swaggerdemo.web; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @RestController @RequestMapping("/test") public class UserController { @RequestMapping("/user") public String addUser() { return "hello world"; } }
4、页面展示
http://ip:port/swagger-ui.html
三、Swagger配置
1、枚举参数配置
1.1 RequestHandlerSelectors
.apis(RequestHandlerSelectors.basePackage("com.lydms.swaggerdemo"))
any()
// 扫描所有，项目中的所有接口都会被扫描到 RequestHandlerSelectors.any()
none()
// 不扫描接口(RequestHandlerSelectors配置如何扫描接口) RequestHandlerSelectors.none()
basePackage()
// 根据包路径扫描接口 RequestHandlerSelectors.basePackage("com.lydms.swaggerdemo")
withMethodAnnotation()
// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求 RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)
withClassAnnotation()
// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口 RequestHandlerSelectors.withClassAnnotation(RestController.class)
1.2 PathSelectors
any()
// PathSelectors.any()
none()
// PathSelectors.none()
ant()
// paths()。过滤什么路径 PathSelectors.ant("/test/**")
regex()
// 通过正则表达式路径url，进行文档生成 PathSelectors.regex("/test")
2、Swagger基本信息配置
Docket：摘要对象，通过对象配置描述文件的信息。apiInfo：设置描述文件中info。参数类型ApiInfo。select()：返回ApiSelectorBuilder对象，通过对象调用build()可以创建Docket对象ApiInfoBuilder：ApiInfo构建器。
//Swagger信息配置 @Bean public Docket docket() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(this.apiInfo()); } //配置文档信息 private ApiInfo apiInfo() { Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱"); return new ApiInfoBuilder() .title("Swagger学习") // 标题 .description("学习演示如何配置Swagger") // 描述 .version("v1.0") // 版本 .termsOfServiceUrl("http://terms.service.url/组织链接") // 组织链接 .contact(contact) // 联系人信息 .license("Apach 2.0 许可") // 许可 .licenseUrl("许可链接") // 许可连接 .extensions(new ArrayList<>()) // 扩展 .build(); }
配配置后展示：
3、配置扫描包位置
配置扫描方式：
select()：paths()：过滤接口的路径apis()方法设置哪个包中内容被扫描
//Swagger信息配置 @Bean public Docket docket() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(this.apiInfo()) .select() // 通过.select()方法获取Docket中的选择器，去配置扫描接口。RequestHandlerSelectors配置如何扫描接口 .apis(RequestHandlerSelectors.basePackage("com.lydms.swaggerdemo")) // 根据包路径扫描接口 .apis(RequestHandlerSelectors.any()) // 扫描所有，项目中的所有接口都会被扫描到 .apis(RequestHandlerSelectors.none()) // 不扫描接口(RequestHandlerSelectors配置如何扫描接口) // 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求 .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)) // 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口 .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)) .paths(PathSelectors.ant("/test/**")) //paths()。过滤什么路径 .paths(PathSelectors.regex("/test")) //通过正则表达式路径url，进行文档生成 .build(); }
paths中PathSelectors参数：
any() // 任何请求都扫描 none() // 任何请求都不扫描 regex(final String pathRegex) // 通过正则表达式控制 ant(final String antPattern) // 通过ant()控制
4、配置Swagger开关
关闭Swagger页面展示
return new Docket(DocumentationType.SWAGGER_2) .enable(false); //配置是否启用Swagger，如果是false，在浏览器将无法访问
根据当前所处的环境，决定是否开启Swagger。
指定当前环境(dev环境)
spring.profiles.active=dev
配置代码：
//Swagger信息配置 public Docket docket(Environment environment) { // 设置要显示swagger的环境 Profiles profiles = Profiles.of("dev", "int", "test"); // 判断当前是否处于该环境 // 通过 enable() 接收此参数判断是否要显示 boolean flag = environment.acceptsProfiles(profiles); return new Docket(DocumentationType.SWAGGER_2) .enable(flag) //配置是否启用Swagger，如果是false，在浏览器将无法访问 .select() .apis(RequestHandlerSelectors.basePackage("com.lydms.swaggerdemo")) // 根据包路径扫描接口 .build(); }
5、配置多个分组
//配置多个分组 @Bean public Docket docket1() { return new Docket(DocumentationType.SWAGGER_2).groupName("group1"); } @Bean public Docket docket2() { return new Docket(DocumentationType.SWAGGER_2).groupName("group2"); } @Bean public Docket docket3() { return new Docket(DocumentationType.SWAGGER_2).groupName("group3"); }
6、自定义注解不扫描包
自定义注解
package com.lydms.swaggerdemo.anno; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; @Target({ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) public @interface MySwagger { }
Swagger配置
//5、自定义：使用注解，不生成文档 @Bean public Docket docket() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(this.apiInfo()) .select() // 注解加载指定方法上不展示(Predicates.not)取反 .apis( Predicates.not( //取反 RequestHandlerSelectors.withMethodAnnotation(MySwagger.class) //根据注解配置 )) .build(); }
使用注解
/** * @MySwagger注解：自定义忽略生成Swagger文档 */ @MySwagger @GetMapping("/testInterface") public String notSwagger(int pageNo, int pageSize) { return "pageNo=" + pageNo + "; pageNo=" + pageSize; }
四、API中使用Swagger
1、Swagger注解
@Api：用在请求的类上，表示对类的说明
@Api：用在请求的类上，表示对类的说明 tags="说明该类的作用，可以在UI界面上看到的注解" value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
@ApiOperation：用在请求的方法上，说明方法的用途、作用
@ApiOperation：用在请求的方法上，说明方法的用途、作用 value="说明方法的用途、作用" notes="方法的备注说明"
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParams：用在请求的方法上，表示一组参数说明 @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面 name：参数名 value：参数的汉字说明、解释 required：参数是否必须传 paramType：参数放在哪个地方 · header --> 请求参数的获取：@RequestHeader · query --> 请求参数的获取：@RequestParam · path（用于restful接口）--> 请求参数的获取：@PathVariable · div（不常用） · form（不常用） dataType：参数类型，默认String，其它值dataType="Integer" defaultValue：参数的默认值
@ApiResponses：用在请求的方法上，表示一组响应
@ApiResponses：用在请求的方法上，表示一组响应 @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息 code：数字，例如400 message：信息，例如"请求参数没填好" response：抛出异常的类
@ApiIgnore: 忽略文档或者忽略方法接口生成
@ApiIgnore: 忽略文档或者忽略方法接口生成
@ApiModel：用于响应类上，表示一个返回响应数据的信息
@ApiModel：用于响应类上，表示一个返回响应数据的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在属性上，描述响应类的属性
@ApiModelProperty：用在属性上，描述响应类的属性
2、Controller中使用
2.1 @Api( )
@Api是类上注解。控制整个类生成接口信息的内容。
tags：类的名称。可以有多个值，多个值表示多个副本。description：描述，已过时。
@Api(tags = "Swagger测试接口") @RestController @RequestMapping("/test") public class UserController { }
2.2 @ApiOperation()-类/方式
@ApiOperation写在方法上，对方法进行总体描述
value：接口描述notes：提示信息
@ApiOperation( value = "新增用户") @ApiResponses({@ApiResponse(code = 200, message = "OK", response = MyUser.class) @PostMapping("/user") public MyUser user() { MyUser myUser = new MyUser(); myUser.setName("张三"); myUser.setAge(18); myUser.setId("123123123"); System.out.println(myUser.toString()); return myUser; }
2.3 @ApiParam()
@ApiParam写在方法参数前面。用于对参数进行描述或说明是否为必添项等说明。
name：参数名称value：参数描述required：是否是必须
@GetMapping("/user01") public MyUser myUser(@ApiParam(name="用户名",value = "新增用户时提供的用户名",required = true) String username, @ApiParam(name = "密码",value = "新增用户时提供的密码",required = true)String password) { MyUser myUser = new MyUser(); myUser.setName(username); myUser.setPassword(password); return myUser; }
2.4 @ApiResponses()
- @ApiOperation(value = “新增用户”)
- @ApiResponses({@ApiResponse(code = 200, message = “OK”, response = MyUser.class)})
@ApiOperation( value = "新增用户") @ApiResponses({@ApiResponse(code = 200, message = "OK", response = MyUser.class) @PostMapping("/user") public MyUser user() { MyUser myUser = new MyUser(); myUser.setName("张三"); myUser.setAge(18); myUser.setId("123123123"); System.out.println(myUser.toString()); return myUser; }
2.5 @ApiImplicitParams()
@ApiImplicitParam用在方法上，表示单独的请求参数，总体功能和@ApiParam类似。
name：属性名value：描述required：是否是必须的paramType：属性类型dataType：数据类型
/** * @ApiImplicitParams：对入参进行解析注解。等同于@ApiParam */ @GetMapping("/testPage") @ApiImplicitParams({ @ApiImplicitParam(name = "pageNo", value = "第几页", required = true, paramType = "字符串", defaultValue = "1"), @ApiImplicitParam(name = "pageSize", value = "每页显示多少条", required = true, paramType = "字符串", defaultValue = "10") }) public String page(String pageNo, String pageSize) { return "pageNo=" + pageNo + "; pageNo=" + pageSize; }
2.6 @ApiIgnore()
@ApiIgnore用于方法或类或参数上，表示这个方法或类被忽略。
/** * @ApiIgnore：忽略生成API帮助文档 */ @ApiIgnore @GetMapping("/testInterface") public String ignore(int pageNo, int pageSize) { return "pageNo=" + pageNo + "; pageNo=" + pageSize; }
3、model中使用Swagger
3.1 @ApiModel()
@ApiModel是类上注解，主要应用Model，也就是说这个注解一般都是写在实体类上。
value：名称description：描述
3.2 @ApiModelProperty()
@ApiModelProperty可以用在方法或属性上。用于当对象作为参数时定义这个字段的内容。
value：描述name：重写属性名required：是否是必须的example：示例内容hidden：是否隐藏。
package com.lydms.swaggerdemo.entity; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; @ApiModel(value = "com.lydms.swaggerdemo.entity.MyUser", description = "新增用户参数") public class MyUser { @ApiModelProperty(value = "ID") private String id; @ApiModelProperty(value = "名称",name = "test",required = true,example = "张三",hidden = true) private String name; @ApiModelProperty(value = "年龄") private int age; @ApiModelProperty(value = "密码") private String password; }
