端点按资源 swagger 注释分组? [英] endpoints group by resources swagger annotation?
问题描述
我正在使用 Spring 进行 REST API 开发.我有一些 API,其中有很多端点.当我打开 swagger ui 时,它看起来很紧凑.
我刚刚阅读了
********** 解决方案 2:(使用标签) **********
你不需要定义多个Docket
bean,一个就够了.
@Bean公共文档库 api1() {//这里的标签是可选的,它只是在 UI 中添加了一个描述//默认描述是类名,所以如果你使用相同的标签//`@Api` 在不同的类上它会选择一个类名作为//描述,所以最好为他们定义你自己的描述返回新的 Docket(DocumentationType.SWAGGER_2).tags(new Tag("users", "users related"),新标签(产品",产品相关")).选择().apis(RequestHandlerSelectors.basePackage("com.github")).建造();}
之后,您只需要使用 @Api
(在类级别,所有方法的默认值)或 @ApiOperation
(在方法级别,将覆盖班级价值).
@RestController@RequestMapping("/api/products")@Api(tags = "产品")公共类产品控制器{@ApiOperation(value = "", tags = "products")@RequestMapping(method = RequestMethod.POST)@ResponseStatus(HttpStatus.CREATED)公共产品 createProduct(@RequestBody 产品产品) {退货;}}
@ApiOperation
(或@Api
)中的标签也可以跨控制器工作,即不同控制器类(或控制器本身)中的方法用给定的标签标记将组合在一起.
I'm using Spring for my REST API development. And I have some API where there are lots of endpoints. When I open up swagger ui, it looks to packed.
I just read this article and saw that we can group endpoints based on resource level.
I just want to know how that can be achieved with swagger annotations with Spring. I appreciate if someone can describe with an example.
And also I just wonder whether we can regroup (higher level grouping) the groups we have deduces in above way?
********** SOLUTION 1: (using groups) **********
Just define multiple Docket
bean for each group, and u will get logical grouping as per your need.
@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();
}
Now you will get two groups in your swagger ui like below.
********** SOLUTION 2: (using tags) **********
You don't need to define multiple Docket
bean just one is enough.
@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();
}
After that you just need to annotate your api methods with @Api
(at class level, default for all methods) or @ApiOperation
(at method level, will override value at class level).
@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;
}
}
Tags in @ApiOperation
(or in @Api
) will work across controller as well, i.e. method in different controller classes (or controller itself) tagged with a given tag will be grouped together.
这篇关于端点按资源 swagger 注释分组?的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持IT屋!