Springboot整合Swagger-ui实现在线API文档
参考:
http://www.macrozheng.com/#/architect/mall_arch_02
https://doc.ruoyi.vip/ruoyi-vue/document/xmjs.html#%E5%90%8E%E7%AB%AF%E6%8A%80%E6%9C%AF
常用注解
- @Api:用于修饰Controller类,生成Controller相关文档信息
- @ApiOperation:用于修饰Controller类中的方法,生成接口方法相关文档信息
- @ApiParam:用于修饰接口中的参数,生成接口参数相关文档信息
- @ApiModelProperty:用于修饰实体类的属性,当实体类是请求参数或返回结果时,直接生成相关文档信息
整合Swagger-ui
一、导入依赖
<!--Swagger-UI API文档生产工具-->
<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>
二、编写swagger-ui的配置文件
@EnableSwagger2
@Configuration
public class Swagger2Config {
@Autowired
private FireworksConfig fireworksConfig;
/**
* 创建API
*
* @return
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//为当前包下controller生成API文档
.apis(RequestHandlerSelectors.basePackage("com.smday.fireworks"))
//为有@Api注解的Controller生成API文档
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
//为有@ApiOperation注解的方法生成API文档
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build()
.securitySchemes(securitySchemes())
.securityContexts(securityContexts());
}
/**
* 设置安全上下文
*
* @return
*/
private List<SecurityContext> securityContexts() {
//设置需要登录认证的路径
List<SecurityContext> result = new ArrayList<>();
result.add(getContextByPath("/admin/.*"));
return result;
}
/**
* 需要认证的路径
*
* @param pathRegex
* @return
*/
private SecurityContext getContextByPath(String pathRegex) {
return SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.regex(pathRegex))
.build();
}
/**
* 默认的安全引用
*
* @return
*/
private List<SecurityReference> defaultAuth() {
List<SecurityReference> result = new ArrayList<>();
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
result.add(new SecurityReference("Authorization", authorizationScopes));
return result;
}
/**
* 安全模式,这里指定token通过Authrization请求头传递
*
* @return
*/
private List<? extends SecurityScheme> securitySchemes() {
//设置请求头信息
List<ApiKey> result = new ArrayList<>();
ApiKey apiKey = new ApiKey("Authorization", "Authorization", "header");
result.add(apiKey);
return result;
}
/**
* 添加摘要信息
*
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("标题:Fireworks个人网站系统接口文档")
.description("fireworks个人网站:用户模块,后台管理模块,收藏模块,日志模块,安全模块")
.contact(new Contact(fireworksConfig.getName(), "https://www.hyhwky.com", "1332790762@qq.com"))
.version("版本号: " + fireworksConfig.getVersion())
.build();
}
}
三、添加注解
@RestController
@RequestMapping("/user")
@Api(tags = "UserController", description = "用户管理")
public class SysUserController {
@PostMapping("/login")
@ApiOperation("登录功能")
public AjaxResult login(@RequestBody UserLoginParam userLoginParam){
AjaxResult ajaxResult = AjaxResult.success();
String token = sysLoginService.login(userLoginParam.getUsername(), userLoginParam.getPassword());
ajaxResult.put("token",token);
return ajaxResult;
}
}
@Data
@AllArgsConstructor
@NoArgsConstructor
public class UserLoginParam {
@ApiModelProperty(value = "用户名", required = true)
@NotEmpty(message = "用户名不能为空")
private String username;
@ApiModelProperty(value = "密码", required = true)
@NotEmpty(message = "密码不能为空")
private String password;
@ApiModelProperty(value = "随机码",required = true)
private String validateCode;
}
四、启动项目,并测试接口,访问url:http://localhost:8083/swagger-ui.html