springboot集成swagger做接口文档说明

swagger在一定程度上给我们节省了很多重复繁琐的工作。在企业开发中，一般我们完成开发的交付给前端调用的时候，一般都要写接口调用文档说明。不要小看这个事情，很麻烦。尤其是有大量接口的时候，并且伴随着系统的不断升级需要调整接口的参数等等。那么，接口调用文档肯定也需要再次修改。这时候，丝袜哥就可以发挥他的优势了。
先来看一下丝袜哥长什么样子：

在spring boot中集成好的swagger启动以后就会长这个样子。
我们看一下如何来搭建这个swagger:
springboot集成swagger步骤：

• 依赖导入

	<!--  这是swagger的核心依赖 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>

    <!--  这是swaggerUI界面的依赖，可以在页面输入"http:localhost:8080/swagger-ui.html"查看
            接口的详细信息
    -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>

• 配置swagger组件

新建一个配置类，复制一下内容到新建的这个类中。（凡是双引号中的内容都可以改变）

    @EnableSwagger2
    @Configuration
    public class SwaggerConfig {
        @Bean
        public Docket creatRestApi(){
            return new Docket(DocumentationType.SWAGGER_2)
                    .pathMapping("/")
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.em.bigdata.controller")) //生成Api要扫描的包
                    .paths(PathSelectors.any())
                    .build().apiInfo(new ApiInfoBuilder()
                            .title("大数据平台对接项目")
                            .description("接口详细信息")
                            .version("v1.0")
                            .contact(new Contact("bigdata","http://localhost:9999/","tuofafa@foxmail.com"))
                            .licenseUrl("http://localhost:9999/")
                            .build());

        }

    }

备注：这个就是swagger的一个配置类。只需要修改双引号里面的内容。使用的时候复制过去即可。

• 各个类中配置如下：
  1.controller中配置如下：

@RestController
@Api(tags = "平台交易信息接口")   //swagger注解 表示这个类是哪个交易信息接口
public class BusinessController {
    @Autowired
    private ClientBusinessServiceImpl businessService;

    ResponseEntity entity = new ResponseEntity();

    /**
     * 商品销售额排行
     * @param count
     * @return
     */
    @RequestMapping(value = "/saleRank",method = RequestMethod.GET)
    @ApiOperation("查询商品销售数量")   //swagger注解  说明这个方法是做什么的
    @ApiImplicitParam(name = "count",value ="返回记录数",defaultValue = "null",required = true paramType = "int")   //swagger注解   给接口中的参数增加说明
    public ResponseEntity getCommoditySaleRank(Integer count) {
        if(StringUtils.isEmpty(count)){
            throw new ParamException("参数为空",2);
        }else {
            return entity.success(this.businessService.commoditySaleRank(count));
        }

    }
}

2.实体类、VO类中配置

/**
 * 交易大屏端
 * @author fafatuo
 * @version 1.0
 * @date 2020/8/20 9:50
 */
@ApiModel  //swagger注解   一般在实体类中配置，给实体类增加说明信息
public class BusinessEnd implements Serializable {

    @ApiModelProperty(value = "平台交易数据")   //swagger注解   一般用在属性上，增加属性的说明信息
    private Business platformBusiness;

    //今日新增订单数量
    @ApiModelProperty(value = "今日新增订单数量")
    private Integer toDayOrderNum;

    //今日新增订单金额
    @ApiModelProperty(value = "今日新增交易金额")
    private BigDecimal toDayOrderMoney;

    //累计交易额
    @ApiModelProperty(value = "累计交易额")
    private BigDecimal cumulativeTransactionAmount;

    public Business getPlatformBusiness() {
        return platformBusiness;
    }

    public void setPlatformBusiness(Business platformBusiness) {
        this.platformBusiness = platformBusiness;
    }

    public Integer getToDayOrderNum() {
        return toDayOrderNum;
    }

    public void setToDayOrderNum(Integer toDayOrderNum) {
        this.toDayOrderNum = toDayOrderNum;
    }

    public BigDecimal getToDayOrderMoney() {
        return toDayOrderMoney;
    }

    public void setToDayOrderMoney(BigDecimal toDayOrderMoney) {
        this.toDayOrderMoney = toDayOrderMoney;
    }

    public BigDecimal getCumulativeTransactionAmount() {
        return cumulativeTransactionAmount;
    }

    public void setCumulativeTransactionAmount(BigDecimal cumulativeTransactionAmount) {
        this.cumulativeTransactionAmount = cumulativeTransactionAmount;
    }

到这里，swagger配置就结束了。
赶紧启动起来访问测试一下：
访问地址：http:localhost:9999/swagger-ui.html
这个地址也是swagger官方提供的。我们只需要修改主机名和端口号就行。其他的都是固定写法。
测试一下：

没有任何问题。
swagger中常用注解的解释
@Api():表明这是一个swagger类资源。一般用在controller的类上。
参数：
tags: 表示说明，例如这是什么controller。有多个tags的时候，是一个list形式的({tags={“用户controller”}})
value: 也是表示说明性的东西。
@ApiOperation():用户方法，表示一个http请求的方法。
参数：
value: 用于对这个接口的描述
notes: 用于提示
tags: 用于重新分组
@ApiModel(): 用于在实体类上对实体类进行标注。
@ApiImplicitParam()：用于对接口方法中的参数进行说明。
参数：
name: 表示传递的参数名，这里跟方法的参数名保持一致
value: 对这个参数字段的说明
defaultValue: 当没有传递值时，方法的默认值是什么
required: 这个参数是否是必须要传递的
@ApiImplicitParams()：用于对接口方法中的参数化进行说明。（用在含有两个及以上的参数环境中）
参数和@ApiImplicitParam()参数一样。
例如：
@ApiOperation(“月累计交易额”)
@ApiImplicitParams({
@ApiImplicitParam(name = “year”,value = “输入年份：例如；2020”,defaultValue = “null”,required = true),
@ApiImplicitParam(name = “count”,value = “返回记录数”,defaultValue = “null”,required = false)
})
@ApiModelProperty： 用于方法，字段； 表示对model属性的说明或者数据操作更改
参数：
value： 字段说明
name： 重写属性名字
dataType： 重写属性类型
required： 是否必填
example： 举例说明
hidden： 隐藏
最后，建议大家在学习的时候，先整体看一遍。看完之后动手搭建一下。根据页面展示的效果在对应到swagger中每个类每个注解。这样，可能就理解每个注解以及每个注解中对应的参数到底有什么意义。