如何在 Swagger 1.5.20 中向 API 控制器添加描述？答案

【问题标题】：How to add description to API controller in Swagger 1.5.20?如何在 Swagger 1.5.20 中向 API 控制器添加描述？
【发布时间】：2021-03-10 23:20:00
【问题描述】：

我正在尝试为 Swagger 中的控制器提供格式化的描述。但是我找不到任何启用它的注释。目前它看起来像这样：

@Api(tags = {"Change timezone"})

但是我想提供有意义的描述。带有@Api 的description 参数已弃用。

【问题讨论】：

你的意思是方法描述？还是控制器描述？
您使用的是哪个版本。我个人使用 l5-swagger，注释是 @OA
@Boug 控制器。
@J-Dumas Swagger 1.5.20.
这里是stackoverflow.com/a/50213515/7237884

标签： java swagger

【解决方案1】：

看来，这种弃用存在漏洞。此功能已被弃用，但没有其他 Annotation 替代该功能。

目前看来您只能以编程方式添加描述

@Bean 
public Docket commonDocketConfig() { 

 return new Docket(DocumentationType.SWAGGER_2) .select() 
       .apis(RequestHandlerSelectors.basePackage("com.company")) 
       .paths(PathSelectors.any()) 
       .build() .apiInfo(apiEndPointsInfo()) 
       .tags(new Tag("Change timezone", "your description")); 
 }

可以在此处跟踪问题

@Api description deprecated without any alternative

你也可以试试

@Api(tags = {"Change timezone"})
@SwaggerDefinition(tags = {
        @Tag(name = "Change timezone", description = "your Description")
})
public class YourController {
}

然而，这个注解已经存在一个未解决的错误@SwaggerDefinition bug

【讨论】：

【解决方案2】：

由于您的操作看起来像是 PUT 操作，请尝试执行类似操作。你也可以这样写：

@OA(
    @PUT(
        tags = {"Change timezone"},
        description = "Your description here",
        etc...
    )
)

这是我拍摄图片的链接：https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations#operation 尝试在那里阅读更多内容。

【讨论】：

我不想描述控制器动作，但控制器本身在问题中已说明。