SpringBoot集成Swagger2

• SpringBoot集成Swagger2
• • @[TOC]
• 前言
• 一、Swagger是什么？
• 二、集成步骤
• • 1.依赖引入
  • 2.代码配置
  • 3.Controller层代码
  • 4.访问路径
  • 5.效果展示
• 总结

本章节主要介绍SpringBoot项目集成Swagger2的一些相关知识，包括集成版本、依赖、集成方式、以及简单的使用。官方提供的SwaggerUI太low，本篇集成了knife4j，在可视化方面有了大大的提示，操作更加人性化。

Swagger是一个restful规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的 工具。在后端服务定义好参数格式以及方法，启动服务后网页即可访问接口信息文档 ，并且在网页端可进行接口测试。Swagger让部署管理和使用功能强大的API变得非常简单。

pom依赖如下，主要列出SpringBoot依赖版本以及Swagger2版本以及knife4j版本，其他需要依赖自行添加

    
        org.springframework.boot
        spring-boot-starter-parent
        2.5.7
        
    
    
        com.github.xiaoymin
        knife4j-spring-ui
        3.0.3
    
    
        io.springfox
        springfox-swagger2
        3.0.0
    

config初始化配置，主要用于初始化swagger以及定义基本信息
basePackage为扫描controller的路径
其他信息按照自己想法定义即可

@Configuration
@EnableSwagger2
public class SwaggerConfig{
    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.oak.mongo.rest.controller"))//扫描的包路径
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("mongo数据库使用接口文档")
                .version("1.0.0")
                .build();
    }
}

定义数据库集合，类似于mysql的表，定义好字段，该处用了lombok表达式，如不需要可自定义set、get方法取代
@Api(tags = {“员工相关接口”}) 定义模块
@ApiImplicitParams({@ApiImplicitParam(name = “param”, value = “员工信息”)})定义参数
@ApiOperation(value = “新增员工”, notes = “新增员工信息”)定义接口名称以及描述
提示：参数定义和方法体内定义需要保持一致，否则会导致Swagger网页访问报错，导致无法打开网页。

@Api(tags = {"员工相关接口"})
@RestController
@RequestMapping("/enp")
public class EmployeeCtrl {

    @Autowired
    private EmployeeService employeeService;

    @ApiImplicitParams({@ApiImplicitParam(name = "param", value = "员工信息")})
    @ApiOperation(value = "新增员工", notes = "新增员工信息")
    @PostMapping("/save")
    public EmployeeDto saveEmploye(@RequestBody EmployeeDto param) {
        return employeeService.insertEmployee(param);
    }

    @ApiImplicitParams({@ApiImplicitParam(name = "id", value = "员工id")})
    @ApiOperation(value = "删除员工", notes = "删除员工信息")
    @PostMapping("/delete")
        public void deleteEmploye(@RequestBody String id) {
        employeeService.deleteEmployee(id);
    }

    @ApiImplicitParams({@ApiImplicitParam(name = "param", value = "员工信息")})
    @ApiOperation(value = "更新员工", notes = "更新员工信息")
    @PostMapping("/update")
    public void updateEmploye(@RequestBody EmployeeDto param) {
        employeeService.updateEmployee(param);
    }

    @ApiImplicitParams({@ApiImplicitParam(name = "id", value = "员工id")})
    @ApiOperation(value = "查询员工", notes = "查询员工信息")
    @PostMapping("/get")
    public EmployeeDto getEmploye(@RequestBody String id) {
        return employeeService.getEmployee(id);
    }
}

http://localhost:port/doc.html#/home

通过mongoTemplate对象对mongoDb数据库进行操作，mongoTemplate有springboot容器创建管理，用户不需要进行配置，使用的时候注入即可，controller层没有贴入，可自行编写。

以上就是SpringBoot集成swagger内容。需要注意的是，不同版本会导致swagger集成后网页访问报错，参数定义不一致也会有同样的问题。