SpringBoot集成Swagger以及Knife4j

本文基于 SpringBoot 进行的集成

集成 Swagger

集成的步骤就几步，首先引入 swagger springboot 启动器依赖，修改 pom.xml：

<!--swagger-->
<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.8.0.RELEASE</version>
</dependency>

当然你可以把 swagger 抽离成一个类似和 common 作用一样的模块公共模块，就是某个微服务需要使用 swagger 依赖一下 swagger 模块即可完成这里不演示这个这里只是记录一下集成 swagger 以及它所对应的皮肤紧接着修改 application.yml 添加如下内容：

#自定义 swagger信息
swagger:
  base-package: top.it6666
  description: BNTang相关接口API文档
  title: BNTangAPI
  version: 1.0

修改启动类启动 swagger：

/**
 * @author BNTang
 * @program myDemoPro
 * @date Created in 2021/10/25 025 14:15
 * @description
 * - swagger文档地址：http://localhost:8081/swagger-ui.html
 **/
@SpringBootApplication
@EnableSwagger2Doc
public class SwaggerApp {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApp.class, args);
    }
}

然后可以添加一个 Controller 进行测试创建 TestController.java 内容如下：

/**
 * 测试控制器
 *
 * @author BNTang
 * @date 2021/10/25
 */
@RestController
@RequestMapping("/swagger/test")
@Api(tags = "测试API接口")
public class TestController {

    @GetMapping("/getList")
    @ApiOperation(value = "获取列表数据", notes = "获取列表下测试数据")
    public String list() {
        return "查询列表数据!";
    }

    @GetMapping("{id}")
    @ApiOperation(value = "获取ID数据", notes = "根据ID获取某条测试数据")
    @ApiImplicitParam(name = "id", value = "主键id", paramType = "path", required = true)
    public String find(@PathVariable Integer id) {
        return String.format("根据主键查询数据: %d", id);
    }

    @PostMapping("/add")
    @ApiOperation(value = "新增数据")
    @ApiParam(name = "test", value = "添加的测试模型实体")
    public String add(@RequestBody Test test) {
        System.out.println(test);
        return "插入数据!";
    }

    @PutMapping("{id}")
    @ApiOperation(value = "更新数据", notes = "根据ID更新测试数据")
    @ApiImplicitParam(name = "id", value = "主键id", paramType = "path", required = true)
    public String update(@PathVariable Integer id,
                         @ApiParam(name = "test", value = "更新的测试模型实体") @RequestBody Test test) {
        System.out.println(test);
        return String.format("根据主键更新一条记录: %d", id);
    }

    @DeleteMapping("{id}")
    @ApiOperation(value = "删除数据", notes = "根据ID删除测试数据")
    @ApiImplicitParam(name = "id", value = "主键id", paramType = "path", required = true)
    public String delete(@PathVariable Integer id) {
        return String.format("根据主键删除记录: %d", id);
    }
}

创建 Test.java 实体类：

/**
 * @author BNTang
 * @program myDemoPro
 * @date Created in 2021/10/25 025 14:51
 * @description
 **/
@Data
public class Test {
    private String name;
}

如上的实体类当中使用到了 lombok 相关的内容所以你可以依赖一下添加如下依赖：

<!--lombok插件-->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
</dependency>

紧接着启动工程访问：host:port/swagger-ui.html 效果如下：

Swagger 汉化

https://www.cnblogs.com/BNTang/articles/14586128.html

集成 Knife4j

通过上图发现 swagger 自带的 UI 不美观，但是呢，有一些开源的爱好的专门开发的一款 Knife4j 的皮肤来美化一下如上的界面同时也进行的增强，如下就是集成的过程和记录首先引入依赖：

<!--knife4j,swagger皮肤-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.6</version>
</dependency>

修改启动类：

/**
 * @author BNTang
 * @program myDemoPro
 * @date Created in 2021/10/25 025 14:15
 * @description
 * - knife4j文档地址：http://localhost:8081/doc.html#/home
 * - swagger文档地址：http://localhost:8081/swagger-ui.html
 **/
@SpringBootApplication
@EnableSwagger2Doc
@EnableKnife4j
public class SwaggerApp {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApp.class, args);
    }
}

在这里我强调一个问题就是如上我说过一个东西你可以把 swagger 抽离成和 common 类似的小模块，如果需要使用 swagger 依赖一下即可，如上这个修改的启动类修改的是依赖 swagger 模块的启动类开启一下 Knife4j 我这里没有演示这个场景你就大概去理解一下，不懂你可以下方留言。经过了如上的配置之后再次启动工程访问：host:port/doc.html 效果如下图所示：