1.SpringBoot web项目集成Swagger2
1.1.认识Swagger2
1.2.集成Swagger2初体验
①基于SpringBoot Initializr来创建一个web项目,并引入相关依赖:
<!--引入swagger2依赖及ui组件--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
依赖组件下载地址:https://mvnrepository.com/artifact/io.springfox
②创建Swagger2Config配置类,增加API应用配置信息:
//将此类交给Spring管理,表示一个配置类 @Configuration //开启Swagger2 @EnableSwagger2 public class Swagger2Config { /** * 创建API应用 * apiInfo() 增加API相关信息 * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现, * 本例采用指定扫描的包路径来定义指定要建立API的目录 * * @return 返回Swagger的Docket配置Bean实例 */ @Bean public Docket createRestApi(Environment environment) { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .enable(true) //enable是否启动swagger,如果为False,则swagger不能在浏览器中访问 .select() //指定API对象扫描哪个包下面的controller //参数any():扫描全部; none():都不扫描 //withClassAnnotation:扫描类上的注解,参数是一个注解的反射对象 //withMethodAnnotation:扫描方法上的注解 .apis(RequestHandlerSelectors.basePackage("com.fengye.swagger2.controller")) //过滤什么路径 .paths(PathSelectors.any()) .build(); } /** * 创建该API的基本信息(这些基本信息会展现在文档页面中) * 访问地址:http://项目实际地址/swagger-ui.html * @return 返回API基本信息 */ private ApiInfo apiInfo() { return new ApiInfoBuilder() //Swagger2展示界面的标题(重要) .title("Spring Boot使用Swagger2构建的Restful API") //描述信息(主要) .description("Swagger2 makes develop more easily") .version("1.0") .termsOfServiceUrl("https://swagger.io/docs") .license("Apache 2.0") .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0") //作者信息 .contact(new Contact("fengye", "https://www.cnblogs.com/yif0118/", "hyfmailsave@163.com")).build(); } }
③创建Controller接口类测试接口:
@RestController @RequestMapping("/oss") @Api(value = "接口演示",description = "用来演示Swagger的一些注解") public class TestController { @ApiOperation(value="修改用户密码", notes="根据用户id修改密码") @ApiImplicitParams({ @ApiImplicitParam(paramType="query", name = "userId", value = "用户ID", required = true, dataType = "Integer"), @ApiImplicitParam(paramType="query", name = "password", value = "旧密码", required = true, dataType = "String"), @ApiImplicitParam(paramType="query", name = "newPassword", value = "新密码", required = true, dataType = "String") }) @RequestMapping("/updatePassword") public String updatePassword(@RequestParam(value="userId") Integer userId, @RequestParam(value="password") String password, @RequestParam(value="newPassword") String newPassword){ if(userId <= 0 || userId > 2){ return "未知的用户"; } if(StringUtils.isEmpty(password) || StringUtils.isEmpty(newPassword)){ return "密码不能为空"; } if(password.equals(newPassword)){ return "新旧密码不能相同"; } return "密码修改成功!"; } }
④启动项目,访问接口url地址信息:
http://项目实际地址/swagger-ui.html
2.Swagger高级配置应用
2.1.多场景启用配置
在实际开发场景中,有时我们需要在开发时使用Swagger接口文档,但是在实际上线或生产环境中并不想使用,那么就需要读取实际环境信息进行启动Swagger。
具体配置如下:
//将此类交给Spring管理,表示一个配置类 @Configuration //开启Swagger2 @EnableSwagger2 public class Swagger2Config { /** * 创建API应用 * apiInfo() 增加API相关信息 * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现, * 本例采用指定扫描的包路径来定义指定要建立API的目录 * * @return 返回Swagger的Docket配置Bean实例 */ @Bean public Docket createRestApi(Environment environment) { //设置要显示的Swagger环境 Profiles profiles = Profiles.of("dev", "test"); //获取当前项目中的环境,看是否一致 boolean flag = environment.acceptsProfiles(profiles); return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .enable(flag) //enable是否启动swagger,如果为False,则swagger不能在浏览器中访问 .select() //指定API对象扫描哪个包下面的controller //参数any():扫描全部; none():都不扫描 //withClassAnnotation:扫描类上的注解,参数是一个注解的反射对象 //withMethodAnnotation:扫描方法上的注解 .apis(RequestHandlerSelectors.basePackage("com.fengye.swagger2.controller")) //过滤什么路径 .paths(PathSelectors.any()) .build(); } }
同时设置相关的环境配置信息:
application.properties:
#确认启用开发环境--swagger启用
spring.profiles.active=dev
application-dev.properties与application-pro.properties:
server.port=8081 #开发环境
server.port=8082 #生产环境
2.2.接口文档分组显示
在实际项目开发过程中,一个项目开发者有成百上千个接口文档,如果不进行分组,那么集合在一个Swagger页面中的接口就会很多,不便于查询和展示,
那么对不同的开发者来进行分组显示,不同的开发者命名自己的开发接口,就非常有必要了。
而Swagger配置中提供了groupName()进行分组显示:
@Bean public Docket devDocket1(){ //由开发者自己管理对应的类,编写controller对应的包 return new Docket(DocumentationType.SWAGGER_2).groupName("A"); } @Bean public Docket devDocket2(){ return new Docket(DocumentationType.SWAGGER_2).groupName("B"); } @Bean public Docket devDocket3(){ return new Docket(DocumentationType.SWAGGER_2).groupName("C"); }
分组效果:
2.3.Swagger Api接口注释
常用到的注解有:
- Api
- ApiModel
- ApiModelProperty
- ApiOperation
- ApiParam
- ApiResponse
- ApiResponses
- ResponseHeader
①Api
Api 用在类上,说明该类的作用。可以标记一个Controller类做为swagger 文档资源,使用方式:
@Api(value = "/user", description = "Operations about user")
②ApiOeration
ApiOperation:用在方法上,说明方法的作用,每一个url资源的定义,使用方式:
@ApiOperation( value = "Find purchase order by ID", notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions", response = Order, tags = {"Pet Store"})
③ApiParam
ApiParam请求属性,使用方式:
public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true) User user)
与Controller中的方法并列使用。
④ApiResponse
ApiResponse:响应配置,使用方式:
@ApiResponse(code = 400, message = "Invalid user supplied")
⑤ApiResponses
ApiResponses:响应集配置,使用方式:
@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
⑥ResponseHeader
响应头设置,使用方法:
@ResponseHeader(name="head1",description="response head conf")
⑦其它
- @ApiImplicitParams:用在方法上包含一组参数说明;
- @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
- paramType:参数放在哪个地方
- name:参数代表的含义
- value:参数名称
- dataType: 参数类型,有String/int,无用
- required : 是否必要
- defaultValue:参数的默认值
- @ApiResponses:用于表示一组响应;
- @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息;
- code: 响应码(int型),可自定义
- message:状态码对应的响应信息
- @ApiModel:描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候;
- @ApiModelProperty:描述一个model的属性。
本博客写作参考文档相关:
https://www.jianshu.com/p/66a14ea07622 《简书--Swagger使用手册》
https://www.jianshu.com/p/12f4394462d5 《简书--Swagger常用注解说明》
https://swagger.io/irc/
示例代码已上传至Github地址:
https://github.com/devyf/SpringBoot_Study/tree/master/springboot_swagger2