端点按资源swagger注释分组？

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注释你的api方法（在类级别，所有方法都是默认的）或@ApiOperation（在方法级别，将覆盖类级别的值）。

@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）中的标签也可以在控制器上运行，即用给定标签标记的不同控制器类（或控制器本身）中的方法将组合在一起。