按资源大摇大摆注释的端点组？

Question

我正在使用 Spring 进行 REST API 开发。我有一些 API，其中有很多端点。当我打开 swagger ui 时，它看起来很拥挤。

我刚刚阅读了 this 文章，发现我们可以根据资源级别对端点进行分组。

我只想知道如何使用带有 Spring 的 swagger 注释来实现这一点。如果有人能举例说明，我将不胜感激。

而且我只是想知道我们是否可以重新组合（更高级别的分组）我们通过上述方式推导出来的组？

Answer 1

************ 解决方案 1：（使用组） **********

只需为每个组定义多个 Docket bean，您将根据需要进行逻辑分组。

@Bean
public Docket api1() {

return new Docket(DocumentationType.SWAGGER_2)
    .groupName("users")
    .select()
    .paths(PathSelectors.ant("/api/users/**"))
    .build();
}

@Bean
public Docket api2() {

return new Docket(DocumentationType.SWAGGER_2)
    .groupName("products")
    .select()
    .paths(PathSelectors.ant("/api/products/**"))
    .build();
}

现在你将得到两个大摇大摆的小组 ui，如下所示。

********** 解决方案 2：（使用标签） **********

你不需要定义多个Docket bean，一个就够了。

@Bean
public Docket api1() {

// here tags is optional, it just adds a description in the UI
// by default description is class name, so if you use same tag using 
// `@Api` on different classes it will pick one of the class name as 
// description, so better define your own description for them
return new Docket(DocumentationType.SWAGGER_2)
    .tags(new Tag("users", "users related"), 
          new Tag("products", "products related"))
    .select()
    .apis(RequestHandlerSelectors.basePackage("com.github"))
    .build();
}

之后你只需要用@Api（在class级别，所有方法的默认值）或@ApiOperation（在方法级别，将覆盖 class 级别的值。

@RestController
@RequestMapping("/api/products")
@Api(tags = "products")
public class ProductController {

    @ApiOperation(value = "", tags = "products")
    @RequestMapping(method = RequestMethod.POST)
    @ResponseStatus(HttpStatus.CREATED)
    public Product createProduct(@RequestBody Product product) {

        return product;
    }
}

@ApiOperation（或 @Api）中的标签也将跨控制器工作，即不同控制器中的方法 classes（或控制器本身）标记有给定标签将组合在一起。

按资源大摇大摆注释的端点组？

endpoints group by resources swagger annotation?

api

rest

spring

swagger

springfox