swaggerAPI接口文档分组

最新推荐文章于 2025-02-21 15:09:29 发布

吾生有牙

最新推荐文章于 2025-02-21 15:09:29 发布

阅读量4.1k

点赞数 1

文章标签： java spring 接口

本文链接：https://blog.youkuaiyun.com/gfdgdshhg/article/details/104365154

版权

本文介绍了如何利用swagger的注解功能对后台API接口进行分组，以应对接口增多导致的查看不便问题。通过创建自定义注解和在配置类中设置Docket，实现了基于注解的接口分类，提高了接口管理的灵活性。但需注意groupName的唯一性和withMethodAnnotation方法对单个注解的限制。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

swagger是一个深度集成的后台API文档工具,极大的方便了后端的开发测试以及和前端的对接工作。但是当项目中的接口越来越多时，会导致页面上的接口过多，查看起来不是很方便，这时可以使用swagger的分组功能将接口进行分组分页展示。分组的规则可以基于路径和注解等，下面主要介绍下基于注解的分类，这种方法比较灵活。

先上结果

分组一

在这里插入图片描述
分组二

在这里插入图片描述

首先定义用于标志分组的注解
在这里插入图片描述
然后在swagger配置类里面创建多个Docket

代码如下

@Configuration
@EnableSwagger2
public class Swagger2 {
    @Bean
    public Docket createApi1() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("分组接口一")
                .apiInfo(apiInfo("分组接口一"))
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(SwaggerApi1.class))
                .paths(PathSelectors.any())
                .build()
                //全局权限验证
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts())
                ;
    }
    @Bean
    public Docket createApi2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("分组接口二")
                .apiInfo(apiInfo("分组接口二"))
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(SwaggerApi2.class))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts())
                ;
    }


    private List<ApiKey> securitySchemes() {
        List<ApiKey> apiKeyList= new ArrayList();
        apiKeyList.add(new ApiKey(AuthUtils.currentUserKey, AuthUtils.currentUserKey, "header"));
        return apiKeyList;
    }
    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContexts=new ArrayList<>();
        securityContexts.add(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
//                        .forPaths(PathSelectors.regex("api/**"))//过滤要验证的路径
                        .build());
        return securityContexts;
    }
    List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences=new ArrayList<>();
        securityReferences.add(new SecurityReference(AuthUtils.currentUserKey, authorizationScopes));
        return securityReferences;
    }

    private ApiInfo apiInfo(String title) {
        return new ApiInfoBuilder()
                .title(title)
                .description("Generated by spring-boot-swagger2.")
                .termsOfServiceUrl("")
                .version("1.0.1")
                .build();
    }
}

需要注意的是groupName不能重复，否则会报错，withMethodAnnotation方法目前只支持单个注解，有点不太方便。
然后是在最终的接口上添加上对应的注解就行了

@RestController
@Api(tags = "功能测试接口",description = "用于测试基础功能，没有实际业务含义")
@RequestMapping("api/test")
@Validated
public class TabTestController {
    @Autowired
    private TabTestService tabTestService;

    @GetMapping
    @ApiOperation("获取列表")
    @SwaggerApi2
    public PageInfo<TabTestVo> list(PageParam pageParam){
        return tabTestService.list(pageParam);
    }
    @PostMapping
    @ApiOperation("添加")
    @SwaggerApi2
    public Long insert(@RequestBody @Validated({Add.class}) TabTestVo tabTest){
        return tabTestService.insert(tabTest);
    }
    @PostMapping("insertBatch")
    @ApiOperation("批量添加")
    @SwaggerApi2
    boolean insertBatch(@RequestBody @Validated({Add.class}) List<TabTestVo> tabTestVos){
        return tabTestService.insertBatch(tabTestVos);
    }
    @PutMapping
    @ApiOperation("修改")
    @SwaggerApi1
    public boolean update(@RequestBody @Validated({Edit.class}) TabTestVo tabTest){
        return tabTestService.update(tabTest);
    }
    @PutMapping("updateBatch")
    @ApiOperation("批量修改")
    @SwaggerApi1
    public boolean updateBatch(@RequestBody @Validated({Edit.class}) List<TabTestVo> tabTestVos){
        return tabTestService.updateBatch(tabTestVos);
    }
    @DeleteMapping
    @ApiOperation("删除")
    @SwaggerApi1
    public boolean del(Long id){
        return tabTestService.del(id);
    }
}