Question

我在Spring MVC项目中使用了以下版本的springfox-swagger2：

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>

我想使用以下swagger文档为我的REST控制器添加描述：

@RestController
@RequestMapping("/admin")
@Api(tags = {"Admin API"})
@SwaggerDefinition(tags = {
    @Tag(name = "Admin API", description = "Admin interface to manage users")
})
public class AdminController {

然而description中的tags并未反映在swagger-ui中。

它说：

管理员API管理控制器

而不是：

管理用户的管理API管理界面

我缺少什么？

Answer 1

我发现我必须配置文档以查看生成的文档中的标记描述：

@Bean
public Docket docket() {
    return new Docket(SWAGGER_2)
        ...
        .tags(
            new Tag("Admin API", "Admin interface to manage users")
        );
}

Answer 2

这是一个从控制器获取注释的版本（我发现将内容保存在控制器上更好）：

@Bean
public Docket docket(ApplicationContext applicationContext) {
    List<Tag> tags = applicationContext.getBeansWithAnnotation(SwaggerDefinition.class).entrySet()
            .stream()
            .flatMap(entry -> Optional.of(entry.getValue().getClass().getAnnotation(SwaggerDefinition.class))
                    .map(swaggerDefinition -> Stream.of(swaggerDefinition.tags())
                            .map(tag -> {
                                String name = tag.name();
                                if (name.isEmpty()) {
                                    name = Paths.splitCamelCase(entry.getKey(), "-").toLowerCase(); 
                                }
                                return new Tag(name, tag.description());
                            }))
                    .orElse(Stream.empty()))
            .collect(Collectors.toList());

    return new Docket(DocumentationType.SWAGGER_2)
    ...
            .tags(tags.get(0), tags.stream().skip(1).toArray(Tag[]::new)); 
}

这将抓取任何带有 SwaggerDefinition 注释的 bean，因此如果这会带来额外的东西，您可能需要进行调整。我最初使用的是 getBeansOfType。

注解不需要指定标签名称。像这样：

@SwaggerDefinition(tags = {
    @Tag(name = "", description = "Admin interface to manage users")
})
public class AdminController {

我使用 Paths.splitCamelCase 方法创建标签名称以匹配默认值。

@Tag中的spingfox-swagger2描述不值得尊敬

2 个答案: