Swagger文档使用说明

一、文档配置 1.1 在API类上添加注解 @Api，例如账户AccountApi类 @Api(tags = "账户管理接口") 1.2 在接口方法上添加注解 @ApiOperation，其中value是接口文档里左边列表名称，notes为右边接口详细描述 @ApiOperation(value = "列表",notes = "列表描述") 1.3 实体类内部属性上加入解释注解 @ApiModelProperty， example调试时会用到，调试时默认显示的值。required 是否必填 @Data public class AccountVOQuery implements Serializable { @ApiModelProperty(value = "项目ID",example = "1369545062727286805",required = true) private Long projectId; @ApiModelProperty(value = "手机号码",example = "13658674352") private String mobile; @ApiModelProperty(value = "运营商ID",example = "1325976554034954294") private Long businessId; @ApiModelProperty(value = "账户状态",example = "Normal") private AccountStatus accountStatus; } 具体注解里作用在截图中体现

1.4 其他类型注解 如果遇到接口地址带参数的情况，或者普通的后面追带参数的形式，使用如下方式 name：字段名称，标识时哪个字段 value：字段藐视 dataType:字段类型 paramType：传参方式 ，有效值为path 、 query 、 body 、 header或form /** * 根据项目用户获取项目账户 * * @param projectId * @param userId * @return */ @GetMapping(value = "/project/{projectId:\\d+}/user/{userId:\\d+}/balance") @ApiImplicitParams({ @ApiImplicitParam(name = "projectId", value = "项目ID", required = true, dataType = "Long", paramType = "path"), @ApiImplicitParam(name = "userId", value = "用户ID", required = false, dataType = "string", paramType = "path")}) public ResponseEntity getProjectAccountBalance(@PathVariable long projectId, @PathVariable long userId) { return null; } 1.5 返回值注释 例如 com.toplion.iot.account.AccountApi#findAccountList这个接口，返回的是分页的数据，具体类型为 AccountVO，在AccountVO类的字段上加入 @ApiModelProperty这个注解填写上用户类型 @Data public class AccountVO { @ApiModelProperty("ID") private Long id; /** * 用户id */ @ApiModelProperty("用户id") private Long userId; /** * 用户名字 */ @ApiModelProperty("用户名字") private String userName; .... } 另外需要对返回类型 ResponseEntity 做下处理，具体方法如下 @GetMapping @ApiOperation(value = "列表",notes = "列表描述") public ResponseEntity findAccountList(AccountVOQuery query, Pageable page) { AccountQuery accountQuery = accountVOMapper.to(query); Page accountDTOS = accountService.listAccount(accountQuery, page.getPageNumber(), page.getPageSize()); return ResponseEntity.ok().body(PaginationVO.of(accountDTOS.map(d -> accountVOMapper.to(d)))); } ResponseEntity中的PaginationVO是一个泛型，需要标识出具体什么类型，swagger才能进行解析，如下代码。像ResponseEntity里的ResponseVO也是泛型形式，也需要标识出具体类型 @GetMapping @ApiOperation(value = "列表",notes = "列表描述") public ResponseEntity[InvalidCharacterError: "PAGINATIONVO<ACCOUNTVO" did not match the Name production] 校验是否充值接口 /** * 校验是否充值 * * @param projectId、 * @return */ @GetMapping(value = "/{projectId:\\d+}/recharge") @ApiOperation(value = "校验是否充值",notes = "校验是否充值") @ApiImplicitParams({ @ApiImplicitParam(name = "projectId", value = "项目ID", required = true, dataType = "Long", paramType = "path"), @ApiImplicitParam(name = "applicationApp", value = "小程序类别", required = true, dataType = "string", paramType = "query")}) public ResponseEntity[InvalidCharacterError: "RESPONSEVO<STRING" did not match the Name production] 二、接口调试 在接口调试前需要添加token，点击文档管理 -> 全局参数->添加参数按钮，参数名称 authorization 参数值为获取到的Bearer +获取到的token，Bearer和Token中间有一个空格 如下图

之后点击下图中的调试按钮，输入好参数，点击发送即可。

三、配置 配置文件在backend.dev.env里，true代表开启swagger文档，不配置默认为false SWAGGER_ENABLE=true 四、访问 249访问 http://192.168.80.249:8880/doc.html 本地访问，需要启动 iot-backend, 端口号要与本地backend配置的一致 http://localhost:8888/doc.html