SpringBoot 集成Swagger2 | 快速生成开发文档 | 敏捷开发

使用 Swagger 开源和专业工具集简化用户、团队和企业的 API 开发。

一、Swagger是什么？

好处

1. 实现更快、标准化的 API 设计

2. 通过协作更智能地工作

3. 托管的交互式 API 文档

二、使用步骤

1.引入Maven库

<!--        swagger依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.22</version>
        </dependency>

如果需要增强版就多引用一个

 <!--knife4j-->
       <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.2</version>
        </dependency>

2.添加SwaggerConfig配置文件

代码如下（示例）：

package com.slh.swagger;


import com.google.common.base.Predicates;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
//@EnableKnife4j
@Configuration
@EnableSwagger2//开启Swagger2
public class SwaggerConfig {
    //配置Swagger用户端
    @Bean
    public Docket docket1(Environment environment){
        //获取项目环境,只在dev环境下才生产API文档
        Profiles profiles = Profiles.of("dev");
        boolean flag = environment.acceptsProfiles(profiles);
        return  new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo("1"))
                .groupName("用户端")
                //ture为开启Swagger
                .enable(flag)
                .select()
                //扫描
                .apis(RequestHandlerSelectors.any())
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                //过滤
                //.paths(PathSelectors.ant("/lijie/**"))
                .build();
    }
    private ApiInfo apiInfo(String contact){
        Contact c = null;
        if (contact.equals("1")){
            c = new Contact("李杰", "", "262231954@qq.com");
        }else if(contact.equals("2")){
            c = new Contact("李跃", "", "ly1045783716@163.com");
        }else{
            c = new Contact("李兴民", "", "lixingmin06@163.com");
        }

        return new ApiInfo(
                "时利和API官方文档",
                "即使再小的帆船也能远航",
                "v1.0",
                "urn:tos", c,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

其中只在dev环境中开启api文档

Java文件注释

package com.slh.entity;

import java.io.Serializable;
import java.math.BigDecimal;
import java.util.Date;

import com.baomidou.mybatisplus.annotation.*;
import com.fasterxml.jackson.annotation.JsonFormat;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import org.springframework.format.annotation.DateTimeFormat;

/**
 * 用户账单实体表
 * 
 * @author lijie
 * @date 2021-06-17
 */
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value="用户账单实体表", description="用户账单实体表")
@TableName("t_user_bill")
public class UserBill implements Serializable {

    private static final long serialVersionUID = 1L;

    /** 主键 */
    @ApiModelProperty(value = "主键",hidden = true)
    @TableId(value="id",type = IdType.ASSIGN_UUID)
    private String id;

    /** 用户id主键 */
    @ApiModelProperty(value = "用户id主键",hidden = true)
    private String userId;

    /** 商家主键id 消费操作填充，充值操作不用填充 */
    @ApiModelProperty(value = "商家主键id 消费操作填充，充值操作不用填充")
    private String businessId;

    /** 账单名称(例如:商家名称、微信充值等) */
    @ApiModelProperty(value = "账单名称(例如:商家名称、微信充值等)")
    private String billName;

    /** 账单类型0消费 1充值 */
    @ApiModelProperty(value = "账单类型0消费 1充值")
    private Integer billType;

    /** 账单交易金额 */
    @ApiModelProperty(value = "账单交易金额")
    private BigDecimal billAmount;

    /** 资金明细id 充值操作填充，消费操作不用填充 */
    @ApiModelProperty(value = "资金明细id 充值操作填充，消费操作不用填充")
    private String userTransactionId;

    /** 红包使用明细id 消费使用红包是填充，其他情况不填充 */
    @ApiModelProperty(value = "红包使用明细id 消费使用红包是填充，其他情况不填充")
    private String redEnvelopeDetailId;

    /** 余额支付金额 消费操作填充，充值操作不用填充 */
    @ApiModelProperty(value = "余额支付金额 消费操作填充，充值操作不用填充")
    private BigDecimal billBalancePay;

    /** 红包支付金额 消费操作填充，充值操作不用填充 */
    @ApiModelProperty(value = "红包支付金额 消费操作填充，充值操作不用填充")
    private BigDecimal billRedEnvelopePay;

    /** 第三方支付金额 消费操作填充，充值操作不用填充 */
    @ApiModelProperty(value = "第三方支付金额 消费操作填充，充值操作不用填充")
    private BigDecimal billThirdpartyPay;

    /** 第三方支付类型 消费操作填充，充值操作不用填充 0、微信 1、支付宝 2、快捷支付 */
    @ApiModelProperty(value = "第三方支付类型 消费操作填充，充值操作不用填充 0、微信 1、支付宝 2、快捷支付")
    private Integer billThirdpartyPayType;

    /** 状态0正常 1已删除 */
    @ApiModelProperty(value = "状态0正常 1已删除",hidden = true)
    @TableLogic
    private Integer billStatus;

    /** 消费订单号 */
    @ApiModelProperty(value = "消费订单号")
    private String orderCode;

    /** 发生交易后余额 */
    @ApiModelProperty(value = "发生交易后余额")
    private BigDecimal billBalance;

    /** 备注 */
    @ApiModelProperty(value = "备注")
    private String billRemarks;

    /** 交易时间 */
    @ApiModelProperty(value = "交易时间",hidden = true)
    @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    @JsonFormat(pattern="yyyy-MM-dd HH:mm:ss",timezone = "GMT+8")
    @TableField(fill = FieldFill.INSERT)
    private Date billDatetime;


}

控制层注释

package com.slh.controller.v1;

import com.slh.common.R;
import com.slh.entity.UserBill;
import com.slh.filter.NeedToken;
import com.slh.service.BillService;
import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

/**
 * @Author Lijie
 * @Description //TODO $
 * @Date 2021年6月17日16:43:04
 * @Version V1.0
 **/
@NeedToken
@RestController
@RequestMapping("/api/v1/bill")
@Api(tags = "账单模块")
public class UserBillController {

    @Autowired
    private BillService billService;

    @ApiOperation(value = "获取用户账单信息列表", notes = "可以根据金额筛选")
    @GetMapping("/selectUserBillList")
    public R<UserBill> selectUserBillList(
            @ApiParam(name = "monthCode", value = "年份月份如:202106", required = false)@RequestParam(required = false) String monthCode,
            @ApiParam(name = "minPrice", value = "最小金额", required = false)@RequestParam(required = false) Integer minPrice,
            @ApiParam(name = "maxPrice", value = "最大金额", required = false)@RequestParam(required = false) Integer maxPrice
    ) {
        return billService.selectUserBillList( monthCode, minPrice, maxPrice);
    }

    @ApiOperation(value = "用户新增账单", notes = "用户新增账单，返回success数量")
    @PostMapping("/addtUserBill")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "businessId", value = "商家id", required = true, dataType = "String"),
            @ApiImplicitParam(paramType = "query", name = "orderCode", value = "订单号", required = true, dataType = "String"),
            @ApiImplicitParam(paramType = "query", name = "billType", value = "账单类型0消费 1充值", required = true, dataType = "int"),
            @ApiImplicitParam(paramType = "query", name = "billAmount", value = "账单交易金额", required = true, dataType = "BigDecimal"),
            @ApiImplicitParam(paramType = "query", name = "billBalance", value = "发生交易后余额", required = true, dataType = "BigDecimal"),
            @ApiImplicitParam(paramType = "query", name = "billName", value = "账单名称(例如:商家名称、微信充值等)", required = true, dataType = "String"),
            @ApiImplicitParam(paramType = "query", name = "redEnvelopeDetailId", value = "红包使用明细id 消费使用红包是填充，其他情况不填充", required = false, dataType = "String"),
            @ApiImplicitParam(paramType = "query", name = "billBalancePay", value = "余额支付金额 消费操作填充，充值操作不用填充", required = false, dataType = "BigDecimal"),
            @ApiImplicitParam(paramType = "query", name = "billRedEnvelopePay", value = "红包支付金额 消费操作填充，充值操作不用填充", required = false, dataType = "BigDecimal"),
            @ApiImplicitParam(paramType = "query", name = "billThirdpartyPay", value = "第三方支付金额 消费操作填充，充值操作不用填充", required = false, dataType = "BigDecimal"),
            @ApiImplicitParam(paramType = "query", name = "billRemarks", value = "备注", required = false, dataType = "String"),
            @ApiImplicitParam(paramType = "query", name = "billThirdpartyPayType", value = "第三方支付类型 消费操作填充，充值操作不用填充 0、微信 1、支付宝 2、快捷支付", required = false, dataType = "String"),
            @ApiImplicitParam(paramType = "query", name = "userTransactionId", value = "资金明细id 充值操作填充，消费操作不用填充", required = false, dataType = "String")
    })
    public R addtUserBill(@RequestBody UserBill userBill) {
        return billService.addtUserBill(userBill);
    }

    @ApiOperation(value = "根据主键id删除用户账单", notes = "删除用户账单，返回success数量")
    @DeleteMapping("/deleteUserBillById")
    public R deleteUserBillById(
            @ApiParam(name = "id", value = "主键id", required = true) @RequestParam String id
    ) {
        return billService.deleteUserBillById(id);
    }

}

---

运行效果

提示：这里对文章进行总结：
例如：以上就是今天要讲的内容，本文仅仅简单介绍了swagger的使用，而swagger提供了大量能使我们快速便捷地处理文档。