@DocApi

doc-apis默认生成当前项目内所有符合框架内置规则的接口(规则包含加了@RestController注解,@Controller注解等多种特征符合其一即可),如果您不希望把所有的接口都生成接口文档, 可以通过前面配置章节提到的doc-apis.autoGenerate=false 来取消这个默认规则, 取消后,您可以通过@DocApi来指定哪些接口需要生成接口文档.

当@DocApi声明在接口方法上的时候，它还拥有一些更灵活的设置：

• result: 这个可以直接声明返回的对象类型,如果你声明了,将会覆盖SpringBoot的返回对象
• stringResult: 返回字符串，在返回结果比较简单,而不想创建一个专门的返回类,则可以考虑使用这个属性
• url: 请求URL,扩展字段,用于支持非SpringBoot项目
• method: 请求方法,扩展字段,用于支持非SpringBoot项目

示例：

@DocApi(result = AdminVO.class, url = "/api/v1/admin/auth", method = "post") stringResult 实例，在文档中将会自动格式化json字符串：

@DocApi(stringResult = "{code: 200, data: 'success'}") @GetMapping(value = "custom-json") public Map customJsonResult(){}

@DocIgnore

忽略指定Controller

忽略某个Controller,你只需要在该Controller类上添加该注解即可,这样整个Controller内的所有接口都会被忽略掉： DocIgnore public class UserController { }

忽略指定方法

当然您也可以把该注解加在具体的方法上,仅忽略该Controller中的的该指定方法,以达到更细粒度的控制:

@DocIgnore
@PostMapping("save")
public ApiResult saveUser(){
return null;
}

忽略指定字段

如果你不想导出对象里面的某个字段,可以给这个字段加上@DocIgnore注解,如此即可在生成接口文档时忽略该字段：

public class User{
   // 省略其它无关字段... 
  
   /**
    * 姓名
    */
   @DocIgnore
   private String name;
}

特别注意

1.框架默认采用Controller类上面的注释内容作为文档的导航标题,但当注释内容中出现@description时,则使用description作为导航标题,例如:

/**
 * 演示一些比较特殊的声明方法
 *
 * @description 管理员接口
 */
@Controller
public class AdminController {
}

则接口文档生成后,导航标题为: 管理员接口, 而非演示一些比较特殊的声明方法

2.在方法的注释中加上@description,则可以在接口方法下面添加一行说明,例如:

 /**
  * 用户列表
  * @description 前端同学请注意, 一切责任,全在前端
  */
  @PostMapping("/list")
  public ApiResult<List<User>> listUser(){}

则接口文档生成后,接口方法下面会多出一行追加的说明: 前端同学请注意, 一切责任,全在前端