一、Swagger-UI是什么？
Swagger-UI是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger-UI是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器。
这个解释简单点来讲就是说，swagger-ui是一款可以根据resutful风格生成的生成的接口开发文档，并且支持做测试的一款中间软件。
二、搭建Swagger-UI
1、引入maven依赖
<!--引入swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
2、添加SwaggerUI的配置
注意：Swagger对生成API文档的范围有三种不同的选择：
- 生成指定包下面类的API的文档
- 生成有指定注解的类的API文档
- 生成有指定注解的方法的API文档
SwaggerUIConfing:
@Configuration
@EnableSwagger2
public class SwaggerUIConfig {
@Bean
public Docket api(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select() //函数返回一个ApiSelectorBuilder实例来控制哪些接口暴露给Swagger来展现
.apis(RequestHandlerSelectors.basePackage("com.alone.springboottest.controller"))
//为有API注解的Controller生成API注解
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
//为有@APiOperation注解的方法生成API文档
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
//在页定义面上显示的标题信息
public ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("Swagger-UI Test")
.version("1.0")
.description("CRUD")
.build();
}
SwaggerUI注解
SwaggerUI常用注解：
- @Api:作用在类上，说明该类的作用
- @ApiOperation:注解来给API增加方法说明
- @ApiImplicitParams:用在方法上包含一组参数说明
- @ApiImplicitParam:给方法入参增加说明
- @ApiResponse:用于表示一组响应
- @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好" response：抛出异常的类- @ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
- @ApiModelProperty：描述一个model的属性
三、在项目中集成Swagger
1、在Controller中使用注解
例：
@Controller
@Api(tags = "UmsAdminController", description = "后台用户管理")
@RequestMapping("/admin")
public class AdminController {
@Autowired
private AdminService adminService;
@Value("${jwt.tokenHeader}")
private String tokenHeader;
@ApiOperation(value = "用户注册")
@RequestMapping(value = "/register", method = RequestMethod.POST)
@ResponseBody
public AdminUser register(@RequestBody AdminUser umsAdminParam) {
AdminUser Admin = adminService.register(umsAdminParam);
if (Admin == null) {
return null;
}
return Admin;
}
@ApiOperation(value = "登录以后返回token")
@RequestMapping(value = "/login", method = RequestMethod.POST)
@ResponseBody
public Map<String,String> login(@RequestBody AdminUser adminUser) {
String token = adminService.login(adminUser.getUsername(), adminUser.getPassword());
if (token == null) {
System.out.println("aaaaaaaaaaaaa");
return null;
}
Map<String, String> tokenMap = new HashMap<>();
tokenMap.put("token", token);
return tokenMap;
}
@ApiOperation("获取用户所有权限（包括+-权限）")
@RequestMapping(value = "/permission/{adminId}", method = RequestMethod.GET)
@ResponseBody
public List<UserPermission> getPermissionList(@PathVariable Long adminId) {
List<UserPermission> permissionList = adminService.getPermissionList(adminId);
return permissionList;
}
@ApiOperation("权限测试-admin")
@RequestMapping(value = "/test",method = RequestMethod.GET)
@ResponseBody
@PreAuthorize("hasAuthority('/user/admin')")
public String permissionTest(){
return "succes";
}
}
在类和方法上添加响应的注解
2、访问本地接口
可以看出访问的url都很清晰的展示在它最终的页面上，我们打开一个方法：可以看出方法的请求参数清晰的的罗列出来，包括方法的返回值。并且有一个很重要的功能，只需要点下方的try it out就可以进行接口测试.
四、使用Swagger的其他问题
1、当RESTful风格的服务器需要token认证时
当接口需要添加token参数进行登录测试时，可以修改Swagger的配置文件：
在SwaggerUIConfig类中的api方法中返回Docket对象之前调用Docket对象.securitySchemes()方法设置一个请求头信息。即添加如下代码：
@Configuration
@EnableSwagger2
public class SwaggerUIConfig {
@Bean
public Docket api(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
········
//添加登录认证
.securitySchemes(securitySchemes());
}
······
private List<ApiKey> securitySchemes(){
//设置请求头信息
List<ApiKey> result=new ArrayList<>();
ApiKey apiKey=new ApiKey("Authorization","Authorization","header");
result.add(apiKey);
return result;
}
}
后即可在在线文档页面中添加token:
