SpringBoot【Swagger2的集成和使用】

Swagger2介绍

Swagger是一款RESTful接口的文档在线自动生成、功能测试功能框架。一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务，加上swagger-ui，可以有很好的呈现。

SpringBoot集成Swagger2

首先添加依赖

<!--swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

编写Swagger2Config配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {


    //是否开启swagger，正式环境一般是需要关闭的，可根据springboot的多环境配置进行设置
    @Value("${swagger.enabled}")
    Boolean swaggerEnabled;

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
				// 当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.jacky.controller"))
                .paths(PathSelectors.any()).build();

    }
    //构建api文档的详细信息函数
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                //页面标题
                .title("这是一个测试服务文档")
                //创建人
                .contact(new Contact("jacky","url","email"))
                //版本号
                .version("1.0")

在Controller层使用Swagger注解


/**
 * class_name: UserController
 * package: com.jacky.controller
 * describe: 用户相关
 * creat_user: Jacky
 * creat_date: 2019/1/16
 * creat_time: 上午9:14
 **/

@Api("swaggerTestController相关api")
@RestController
@RequestMapping(value = "user")
public class UserController extends BaseController{
    
    @PostMapping("update")
    @ApiOperation(value="用户修改")    
    public Map<String,String> updateUser(@Valid @RequestBody UserReq userReq){
 
        if(userReq.getId() == null || "".equals(userReq.getId())) {
            throw new CommonException("0000", "更新时ID不能为空");
        }
        User user = new User();
        user.setCode(userReq.getCode());
        user.setName(userReq.getName());
        user.setId(Long.parseLong(userReq.getId()));        
        userService.updateById(user);
        Map<String,String> result = new HashMap<String,String>();
        result.put("respCode", "01");
        result.put("respMsg", "更新成功");
        return result;
    }
 
    @GetMapping("/get/{id}")
    @ApiOperation(value="用户查询(ID)")    
    @ApiImplicitParam(name="id",value="查询ID",required=true)
    public Map<String,Object> getUser(@PathVariable("id") String id){
        //查询
        User user = userService.selectById(id);
        if(user == null) {
            throw new CommonException("0001", "用户ID：" + id + "，未找到");
        }
        UserResp resp = UserResp.builder()
                .id(user.getId().toString())
                .code(user.getCode())
                .name(user.getName())
                .status(user.getStatus())
                .build();
        Map<String,Object> result = new HashMap<String,Object>();
        result.put("respCode", "01");
        result.put("respMsg", "成功");
        result.put("data", resp);
        return result;
    }
    
}

User实体类

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
//加入@ApiModel
@ApiModel
public class UserReq {
 
    @ApiModelProperty(value="ID",dataType="String",name="ID",example="1020332806740959233")
    String id;
 
    @ApiModelProperty(value="编码",dataType="String",name="code",example="001")
    @NotBlank(message = "编码不能为空")
    String code;
 
    @ApiModelProperty(value="名称",dataType="String",name="name",example="oKong")
    @NotBlank(message = "名称不能为空")
    String name;
}

启动Spirngboot项目，访问启动SpringBoot项目，访问 http://localhost:项目端口/swagger-ui.html就可以看见文档了

Swagger2注解说明

@Api()：作用于类上，表示这个类是swagger的资源。
- ```
tags = ”说明该类的作用“
```
@ApiOperation()：用在请求的方法上，说明的方法的用户和作用
- ```
value=“说明方法的用途、作用”
```
- ```
notes="方法的备注说明“
```
@ApiImplicitParams()：用在请求的方法上，表示一组参数说明，可以包含多个@ApiImplicitParam()

@ApiImplicitParam()：指定一个请求参数的各个方面

```
   name：参数名
```
```
   value：参数的汉字说明
```
```
   required：参数是否必须传
```
```
   dataType：参数类型
```
```
   defaultValue：参数的默认值
```

@ApiResponses()：用在请求的方法上，表示一组响应。可以包含多个@ApiResponse()

@ApiResponse()：用于表示一个错误的响应信息

```
code：数字
```
```
message：信息
```
```
response：抛出异常的类      
```

@ApiModel()：用在响应类上，表示一个返回响应数据的信息。
@ApiModelProperty()：用在属性上，描述响应类的属性

SpringBoot【Swagger2的集成和使用】

Swagger2介绍

SpringBoot集成Swagger2

Swagger2注解说明

猜你喜欢