Swagger笔记

Swagger笔记

简介

• 由于架构革新，进入了前后端分离，服务端只需提供RESTful API的时代。

• 而构建RESTful API会考虑到多终端的问题，这样就需要面对多个开发人员甚至多个开发团队。

• 为了减少与其他团队对接的沟通成本，我们通常会写好对应的API接口文档。

• 从最早开始的word文档，到后续的showdoc，都能减少很多沟通成本，但随之带来的问题也比较麻烦。在开发期间接口会因业务的变更频繁而变动，如果需要实时更新接口文档，这是一个费时费力的工作。

• 为了解决上面的问题，Swagger应运而生。他可以轻松的整合进框架，并通过一系列注解生成强大的API文档。他既可以减轻编写文档的工作量，也可以保证文档的实时更新，将维护文档与修改代码融为一体，是目前较好的解决方案。

常用注解

• @Api

  • 用于类，表示标识这个类是swagger的资源

  • tags 表示说明

  • value 也是说明，可以使用tags替代

    但是tags如果有多个值，会生成多个list

• @ApiOperationSupport

  • 用于方法，在swagger上的先后顺序

• @ApiOperation

  • 用于方法，表示一个http请求的操作

@Api(value = "Exchange", tags = "Exchange接口")
public class ExchangeController extends BladeController {
​
    @Autowired
    private final IExchangeService iExchangeService;
​
    @PostMapping("/save")
    @ApiOperationSupport(order = 1)
    @ApiOperation(value = "新增", notes = "传入exchange")
    public R<Exchange> save(@Valid @RequestBody Exchange exchange) {
        return R.status(iExchangeService.save(exchange));
    }
}

• @ApiParam

  • 用于方法，参数，字段说明，表示对参数的添加元数据（说明或是否必填等）

  • name 参数名

  • value 参数说明

  • required 是否必填

@PostMapping("/remove")
@ApiOperation(value = "逻辑删除", notes = "传入notice")
public R remove(@ApiParam(value = "主键集合") @RequestParam String ids) {
   boolean temp = noticeService.deleteLogic(Func.toIntList(ids));
   return R.status(temp);
}

• @ApiModel

  • 用于类 ，表示对类进行说明，用于参数用实体类接收

  • value 表示对象名

  • description 描述

  • 都可省略

• @ApiModelProperty

  • 用于方法，字段，表示对model属性的说明或者数据操作更改

  • value 字段说明

  • name 重写属性名字

  • dataType 重写属性类型

  • required 是否必填

  • example 举例说明

  • hidden 隐藏

@Data
@TableName("hr_exchange")
@EqualsAndHashCode(callSuper = true)
@ApiModel(value = "exchange对象", description = "exchange对象")
public class Exchange extends BaseEntity implements Serializable {
​
   private static final long serialVersionUID = 1L;
​
   /**
    * 主键
    */
   @JsonSerialize(using = ToStringSerializer.class)
   @ApiModelProperty(value = "主键")
   @TableId(value = "id", type = IdType.ASSIGN_ID)
   private Long id;
}

• @ApiIgnore()

  • 用于类，方法，方法参数，表示这个方法或者类被忽略

@ApiIgnore()
@GetMapping("/detail")
public R<Notice> detail(Integer id) {
   Notice detail = noticeService.getOne(id);
   return R.data(detail );
}

• @ApiImplicitParams()

  • 用于方法，包含一组参数说明 @ApiImplicitParam

• @ApiImplicitParam()

  • 用于方法，指定一个请求参数的各个方面

  • paramType：参数放在哪个地方

  • header-->请求参数的获取：@RequestHeader

  • query-->请求参数的获取：@RequestParam

  • path（用于restful接口）-->请求参数的获取：@PathVariable

  • body（不常用）

  • form（不常用）

  • name：参数名

  • dataType：参数类型

  • required：参数是否必须传

  • value：参数的意思

  • defaultValue：参数的默认值

@GetMapping("/list")
@ApiImplicitParams({
    @ApiImplicitParam(name = "category",value = "公告类型",
                     paramType = "query", dataType = "integer"),
    @ApiImplicitParam(name = "title",value = "公告标题",
                     paramType = "query", dataType = "string")})
@ApiOperation(value = "分页", notes = "传入notice")
public R<IPage<Notice>> list(@ApiIgnore @RequestParam Map<String, Object> notice, Query query) {
   IPage<Notice> pages = noticeService.page(Condition.getPage(query), Condition.getQueryWrapper(notice, Notice.class));
   return R.data(pages );
}

• @ApiResponses

  • 用于表示一组响应

• @ApiResponse

  • code：数字，例如400

  • message：信息，例如"请求参数没填好"

  • response：抛出异常的类

@GetMapping("/detail")
@ApiOperation(value = "获取用户详细信息", notes = "传入notice")
@ApiResponses(value = {
    @ApiResponse(code = 500, msg= "INTERNAL_SERVER_ERROR", 
                 response = R.class)})
public R<Notice> detail(Integer id) {
   Notice detail = noticeService.getOne(id);
   return R.data(detail );
}