Swagger中@Api注解踩坑记录

背景

在使用Java开发接口时，我们通常使用Swagger这种接口插件来帮助我们管理和生成接口文档。往往我们需要相关Java代码加上Swagger的相关注解，来完成对接口的说明和帮助生成文档。本文主要讲述在使用Swagger @Api注解时所遇到到问题和解决方案。

现象

在接口注释@Api注解时，使用方式如下：


@Api(tag = "Swagger 接口文档")
public class SwaggerController{
		@ApiOperation(xxx)
		public void api(){
			...
		}
}

当注释生效时，我们Swagger前端页面上会显示一列菜单，菜单名称为“Swagger 接口文档”，菜单下的列表为该类中标注了@ApiOperation定义的接口。

然而，当你以下面方式命名你的tag文件时：


@Api(tag = "Swagger/接口文档")
public class SwaggerController{
		@ApiOperation(xxx)
		public void api(){
			...
		}
}

你会发现你菜单页面下的接口为空白，你编写的接口并没有被放进接口目录下。

原因

查看Swagger前端功能时，发现Swagger请求接口中返回的数据是正常的，但是在前端展示时，“Swagger/接口文档“字段会被修改为”Swagger-接口文档“，其中的”/“符号都被替换成了”-“符号，这样下来，tag名称和接口的对应关系与后端返回的结果已经不能够对上，使用“Swagger-接口文档”不再能找到其下的接口，因此在展示时认为没有写相关接口数据。

解决方案

在使用Swagger@Api注解时，我们应该在tag中尽量避免使用“/”符号，以免出现上述情况。尽量避变使用接口描述符字段，来保证插件生成文档正常。