【SpringBoot】SpringBoot整合Swagger

简介

痛点：

前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写和维护接口文档耗费精力，特别是更新大型项目时候，冗余的接口和代码造成后续开发的各种坑（跨中心调用错误等），这时候Swagger就出现了。按照新的开发模式，在迭代的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，真正做到一致性。

Demo效果图：

Spring整合引言：

spring-swagger项目，就是现在的Springfox

可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码

Swagger相关资料及官网：

• Swagger官网： https://swagger.io/
• 本机访问SwaggerDemo地址： http://localhost:8080/swagger-ui.html

---

Swagger工具 了解

---

构建Swagger与SpringBoot环境

Swagger注解介绍

@Api

• 作用：用来指定接口的描述文字
• 修饰：作用在类上
• tags属性：@Api(tags=“登录”)；接口描述文字

@ApiOperation

• 作用：用来指定接口的描述文字
• 修饰：作用在方法上
• value&notes属性：value描述，notes详细描述

 @ApiOperation(value = "查询所有用户接口",
               notes ="<span style='color:red;'>描述:</span>&nbsp;用来查询所有用户信息的接口" )

@ApiImplicitParams

• 作用：用来对接口中的参数进行说明
• 修饰：在方法上

    @ApiImplicitParams({
            // 一个@ApiImplicitParam只能描述一个变量
            //name对应变量名，value对应变量的描述，dataType对应类型,defaultValue默认swagger测试的初始值，paramType对应参数从path中获取
            @ApiImplicitParam(name = "id",value ="用户id",dataType = "String",defaultValue = "01",paramType = "path"),
            @ApiImplicitParam(name = "name",value ="用户姓名",dataType = "String",defaultValue = "zdy",paramType = "path")
    })

@ApiResponses

作用：用于请求的方法上，标识一组响应
修饰：在方法上

@ApiResponses({
            @ApiResponse(code=401, message = "当前请求没有被授权"),
            @ApiResponse(code=404, message = "当前请求路径不存在"),
            @ApiResponse(code=200, message = "保存用户信息成功")
    })

---

Swagger入门Demo

1.构建SpringBoot项目

选择以下依赖模块

导入Swagger依赖

 <!--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>

2.构建Swagger文件夹编写Swagger配置类

新建swagger文件夹和config目录，编写SwaggerConfig类

//@EnableSwagger2 开启Swagger配置扫描
@Configuration
@EnableSwagger2
public class SwaggerConfig {
   @Bean
   public Docket createRestApi(){
       //Docket 代表接口文档
       //SWAGGER_2 Swagger规范
       return new Docket(DocumentationType.SWAGGER_2)
               .pathMapping("/")
               .select()
               //apis：扫描哪个接口的包
               .apis(RequestHandlerSelectors.basePackage("com.ryoujou.controller"))
               .paths(PathSelectors.any())
               //apiInfo：信息
               .build().apiInfo(new ApiInfoBuilder()
                       .title("标题：SpringBoot整合Swagger使用")
                       //描述详细信息
                       .description("SpringBoot整合Swagger，详细信息……")
                       //定义自己的版本
                       .version("1.0")
                       //构建者信息
                       .contact(new Contact("zdy","http://www.ryoujou.com","820657457@qq.com"))
                       .license("The ryoujou License")
                       .build());
   }
}

3.编写需要调用的实体类

新建entity目录，编写User类，需要lombok插件

@Data
@AllArgsConstructor
@NoArgsConstructor
@ToString
@Accessors(chain = true)
public class User {
    private String id;
    private String name;
}

4.编写具体的Controller和Api

新建controller目录，编写UserController类

@RestController
@RequestMapping("user")
@Api(tags = "用户服务相关接口描述")
public class UserController {
   @GetMapping("findAll")
   @ApiOperation(value = "查询所有用户接口",
                 notes ="<span style='color:red;'>描述:</span>&nbsp;用来查询所有用户信息的接口" )
   public Map<String, Object>  findAll(){
       Map<String, Object> map = new HashMap<String, Object>();
       map.put("success","查询所有成功");
       map.put("state",true);
       return map;
   }

   //path中获取信息
   @PostMapping("save/{id}/{name}")
   @ApiOperation(value = "RESTful风格保存用户信息接口",
           notes ="<span style='color:red;'>描述:</span>&nbsp;用来保存用户信息的接口" )
   @ApiImplicitParams({
           // 一个@ApiImplicitParam只能描述一个变量
           //name对应变量名，value对应变量的描述，dataType对应类型,defaultValue默认swagger测试的初始值，paramType对应参数从path中获取
           @ApiImplicitParam(name = "id",value ="用户id",dataType = "String",defaultValue = "01",paramType = "path"),
           @ApiImplicitParam(name = "name",value ="用户姓名",dataType = "String",defaultValue = "zdy",paramType = "path")
   })
   // 参数入参@PathVariable(，从path中获取
   public Map<String, Object>  save(@PathVariable("id") String id, @PathVariable("name") String name){
       System.out.println("id:"+id);
       System.out.println("name:"+name);
       Map<String, Object> map = new HashMap<String, Object>();
       map.put("success","查询所有成功");
       map.put("state",true);
       return map;
   }

   //body-json方式：调用User实体类就不需要用Swagger注解进行参数描述，会自动生成
   @PostMapping("save")
   @ApiOperation(value = "body-json方式保存用户信息接口",
           notes ="<span style='color:red;'>描述:</span>&nbsp;用来保存用户信息的接口" )
   //
   @ApiResponses({
           @ApiResponse(code=401, message = "当前请求没有被授权"),
           @ApiResponse(code=404, message = "当前请求路径不存在"),
           @ApiResponse(code=200, message = "保存用户信息成功")
   })
   public Map<String, Object>  save1(@RequestBody User user){
       System.out.println("id:"+user.getId());
       System.out.println("name:"+user.getName());
       Map<String, Object> map = new HashMap<String, Object>();
       map.put("success","查询所有成功");
       map.put("state",true);
       return map;
   }

}

编写完成后运行，输入路径：http://localhost:8080/swagger-ui.html

---

Swagger使用教程

项目运行访问:http://localhost:8080/swagger-ui.html

具体接口：

进行测试：

查看结果：