Swagger2的介绍、基本配置和使用这个帖子讲的很清楚,我就不多说了
链接:https://developer.ibm.com/zh/articles/j-using-swagger-in-a-spring-boot-project/
这里我说一下怎么将接口文档的相关内容单独提出来不影响controller层。
1.创建一个api层,用于单独存放swagger的相应信息.
2.编写controller对应的api接口,如,对UsersController类编写对应的UsersApi接口。
@Api(tags = "用户相关接口")
public interface UsersApi {
/**
* 查询所有
*/
@ApiOperation(value = "按条件查询查询所有")
@ApiImplicitParams({
@ApiImplicitParam(name="page",example = "分页信息"),
@ApiImplicitParam(name="users",example = "用户信息")
})
R selectAll(Page<Users> page, Users users);
@ApiIgnore//这个注解的意思是在接口文档中不显示这个接口
@ApiOperation(value = "删除数据")
R delete(@RequestParam("idList") List<Long> idList);
}
3.然后在UsersController中实现这个接口
效果图:
注意事项:配置文件要扫描到controller层,扫描到api层是扫描不到的,用扫描注解的方式扫描api注解也是不行的。(这些坑我已经试过了)
附上我swagger配置文件:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors
.basePackage("com.xiyu.kgcmanagejava.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("管理系统")
.description("管理系统的API接口文档")
.version("1.0.1")
.build();
}
}
再说一下如果想多级分组怎么配置,
可以扫描同一个包,然后根据路径进行区分就好。
代码:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("管理系统")
.description("管理系统的API接口文档")
.version("1.0.1")
.build();
}
@Bean
public Docket usersApis() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("用户名模块")
.select()
.apis(RequestHandlerSelectors
.basePackage("com.xiyu.kgcmanagejava.controller"))
.paths(PathSelectors.ant("/users**/**"))
.build()
.apiInfo(apiInfo())
.enable(true);
}
@Bean
public Docket controller2Apis() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("角色模块")
.select()
.apis(RequestHandlerSelectors
.basePackage("com.xiyu.kgcmanagejava.controller"))
.paths(PathSelectors.ant("/roles**/**"))
.build()
.apiInfo(apiInfo())
.enable(true);
}
}
效果图: