SpringBoot2.X整合Swagger2

SpringBoot整合Swagger2接口文档

Swagger2的好处

Springboot整合Swagger2，构建RESTful API文档，节省接口文档开发管理的时间，同时也能够自动更新，修改代码，同样提供了在线调试RESTful API的强大功能

SpringBoot2.X整合Swagger2

1. 创建SpringBoot项目并引入SwaggerMaven依赖

<!--主要依赖-->
<parent>
   <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.2.1.RELEASE</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>
<dependencies>
	<dependency>
    	<groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>
	<!--Swagger依赖-->
	<dependency>    
		<groupId>com.spring4all</groupId>    
		<artifactId>swagger-spring-boot-starter</artifactId>    			
		<version>1.9.0.RELEASE</version>
	</dependency>
</dependencies>

2. 在SpringBoot项目的启动类上添加@EnableSwagger2注解

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class SwaggerApplication {    
    public static void main(String[] args) {        				
        	SpringApplication.run(SwaggerApplication.class, args);    
    }
}

3. 创建一个新的Swagger2配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {    
    @Bean    
    public Docket createApiInfo() {        
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo()).select()
            .apis(RequestHandlerSelectors
                  .basePackage("com.daop.swagger.controller")) 
            .paths(PathSelectors.any())
            .build();    
    }    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("swagger构建API文档")//接口文档的标题
            .description("RestFul风格接口")//接口文档的描述
            .termsOfServiceUrl("https://github.com/Gadmind")//更新维护地址
            .version("1.0")//接口文档版本号
            .build();
    }
}

访问路径：项目路径/swagger-ui.html
效果图

Swagger2常用注解解释（可根据项目需求使用不同的注解）

@ApiOperation		//描述一个类的一个方法，或者说一个接口 
@ApiParam			//单个参数描述 
@ApiModel			//用对象来接收参数
@ApiMOdelProperty	//对象中的字段描述
@ApiProperty		//用对象接收参数时，描述对象的一个字段 
@ApiResponse		//描述其中一个响应 
@ApiResponses		//描述多个响应 
@ApiIgnore			//忽略这个API或参数 
@ApiError			//错误返回的信息 
@ApiImplicitParam	//单个请求参数 
@ApiImplicitParams	//多个请求参数

增删改查例子

1. 添加员工

   @ApiOperation(value = "员工添加", notes = "添加新的员工信息")
   @PostMapping("/employee")
   public ResponseEntity<JsonResult> addEmpById(
           @RequestBody@ApiParam(name = "emp",value = "员工实体类") Employees emp) {
           JsonResult result = new JsonResult();
          try {
              result.setResult(employeesMapper.insert(emp));
              result.setCode("800");
          } catch (Exception e) {
              result.setCode("500");
              result.setResult("请求错误");
              e.printStackTrace();
          }
        return ResponseEntity.ok(result);
   }
   

   预览图
   

2. 查询员工列表

   @ApiOperation(value = "员工列表", notes = "查询员工列表")
   @GetMapping("")
   @ApiResponses({@ApiResponse(code = 800, message = "成功"),
               @ApiResponse(code = 500, message = "服务出错")})
   public ResponseEntity<JsonResult> queryEmployees() {
        JsonResult result = new JsonResult();
        try {
            result.setResult(employeesMapper.selectAll());
            result.setCode("800");
        } catch (Exception e) {
            result.setCode("500");
            result.setResult("请求错误");
            e.printStackTrace();
        }
       return ResponseEntity.ok(result);
   }
   

   预览图
   

3. 查询员工

   @ApiOperation(value = "员工查询", notes = "根据ID查询员工信息")
   @ApiImplicitParam(name = "empNo", 
                         value = "员工编号", required = true, paramType = "path")
   @GetMapping("/{empNo}")
   public ResponseEntity<JsonResult> queryEmpById(@PathVariable Integer empNo) {
        JsonResult result = new JsonResult();
   	 try {
           result.setResult(employeesMapper.selectByPrimaryKey(empNo));
           result.setCode("800");
        } catch (Exception e) {
           result.setCode("500");
           result.setResult("请求错误");
           e.printStackTrace();
        }
      return ResponseEntity.ok(result);
   }
   

   预览图
   

4. 修改员工

    @ApiOperation(value = "员工更新", notes = "根据ID更新员工信息")
    @PutMapping("/employee")
    public ResponseEntity<JsonResult> updateEmpById(@RequestBody
        @ApiParam(name = "emp",value = "员工实体类")Employees emp) {
        JsonResult result = new JsonResult();
        try {
            result.setResult(employeesMapper.updateByPrimaryKeySelective(emp));
            result.setCode("800");
        } catch (Exception e) {
            result.setCode("500");
            result.setResult("请求错误");
            e.printStackTrace();
        }
       return ResponseEntity.ok(result);
    }
   

   预览图
   

5. 删除员工

   @ApiOperation(value = "员工删除", notes = "根据ID删除员工信息")
   @ApiImplicitParam(name = "empNo",
                      value = "员工编号", required = true, paramType = "path")
   @DeleteMapping("/{empNo}")
   public ResponseEntity<JsonResult> deleteEmpById(@PathVariable Integer empNo) {
       JsonResult result = new JsonResult();
       try {
            result.setResult(employeesMapper.deleteByPrimaryKey(empNo));
            result.setCode("800");
       } catch (Exception e) {
            result.setCode("500");
            result.setResult("请求错误");
            e.printStackTrace();
       }
     return ResponseEntity.ok(result);
   }
   

   预览图

GitHub源码地址:Spring-boot&Swagger2

来源：CSDN

作者：Mr_DaoPu

链接：https://blog.csdn.net/qq_41574368/article/details/103490498