[Java] SpringBoot中使用Swagger的超简单方法

<!-- Swagger -->
<dependency>
  <groupId>com.battcn</groupId>
  <artifactId>swagger-spring-boot-starter</artifactId>
  <version>2.1.5-RELEASE</version>
</dependency>

spring:
  swagger:
  enabled: true
  title: 标题
  description: 描述信息
  version: 系统版本号
  contact:
    name: 维护者信息
  base-package: swagger扫描的基础包，默认：全扫描(分组情况下此处可不配置)
  #全局参数,比如Token之类的验证信息可以全局话配置
  global-operation-parameters:
  -   description: 'Token信息,必填项'
    modelRef: 'string'
    name: 'Authorization'
    parameter-type: 'header'
    required: true
  groups:
    basic-group:
    base-package: com.battcn.controller.basic
    system-group:
    base-package: com.battcn.controller.system

spring:
  swagger:
  title: 星空小屋 - 文章微服务接口
  description: 文章微服务相关接口，包括文章、模块、知识点管理等
  version: 1.0.0 - SNAPSHOT
  contact:
    name: cv大魔王
    email: 1919301983@qq.com
  host: localhost
  enabled: true
  security:
    filter-plugin: true # 配置账号密码
    username: root
    password: root

对swagger熟悉的小伙伴的请忽略“常用注解段落”

`@Api`：用在 Controller 类上，描述该类的作用
  1. `value`="描述信息"
  2. `description`="详细描述该类的作用"

// 在对象类上使用@ApiModel
@ApiModel(value="CategoryREQ对象", description="类别查询条件")
public class CategoryREQ extends BaseRequest<Category> {
}

• value：属性的描述
  
• hidden：是否是查询条件属性, false:(默认值)在api文档显示，作为查询条件；true 隐藏，不是条件属性
  

// 请求方法参数是 CategoryREQ 对象
public Result search(@RequestBody CategoryREQ req) {}
 
@ApiModel(value="CategoryREQ对象", description="类别查询条件")
public class CategoryREQ extends BaseRequest<Category> {
  
  @ApiModelProperty(value = "分类名称")
  private String name;
 
  @ApiModelProperty(value="状态(1:正常，0:禁用)")
  private Integer status;
}

• @ApiResponses：用在请求的方法上，用于表示一组响应
  
• @ApiResponse：用在 @ApiResponses 中，一般用于表达一个错误的响应信息，注解参数：
  
• code：数字，如 400message：信息，如 “参数填写错误”response：抛出异常的类
  

• name：参数名
  
• value：描述参数的作用
  
• dataType：参数类型，参数类型，默认String，其它值 dataType=“Integer”
  
• defaultValue：参数默认值
  
• required：参数是否必传（true/false）
  
• paramTpye：指定参数放在哪些地方（header/query/path/body/form）
  

// 请求方法有多个请求参数 size， current
@ApiImplicitParams({
  @ApiImplicitParam(name="current", value="页码", required=true, paramType="path",dataType="int"),
  @ApiImplicitParam(name="size", value="每页记录数", required=true, paramType="path",dataType="int")
})
@ApiOperation("根据分类名称与状态查询分类列表接口")
@PostMapping("/search/{current}/{size}")
Result search(@RequestBody CategoryREQ req, @PathVariable int current, @PathVariable int size);