💘10分钟，6个点，SpringBoot集成丝袜哥（Swagger）整的明明白白💘

2022-04-24 234

版权

本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。

简介： 相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。

Springboot整合Swagger2

1. 什么是Swagger

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。

发现了痛点就要去找解决方案。解决方案用的人多了，就成了标准的规范，这就是Swagger的由来。通过这套规范，你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。

但即便如此，对于许多开发来说，编写这个yml或json格式的描述文件，本身也是有一定负担的工作，特别是在后面持续迭代开发的时候，往往会忽略更新这个描述文件，直接更改代码。久而久之，这个描述文件也和实际项目渐行渐远，基于该描述文件生成的接口文档也失去了参考意义。所以作为Java届服务端的大一统框架Spring，迅速将Swagger规范纳入自身的标准，建立了Spring-swagger项目，后面改成了现在的Springfox。通过在项目中引入Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式，在后面需求持续迭代的项目中，显得尤为重要和高效。

2. Swagger注解详解

2.1 @Api可以标记一个 Controller 类作为 Swagger 文档资源

tags：接口说明，可以在页面中显示。可以配置多个，当配置多个的时候，在页面中会显示多个接口的信息。description:对tags 进行描述说明

@RequestMapping("/api")
@Api(tags = "测试swagger接口",description = "User模块")//描述
复制代码

2.2 @ApiModel

@ApiModel 用在类上，表示对类进行说明，用于实体类中的参数接收说明

@Data
@ApiModel(value = "com.pojo",description = "用户pojo")
public class User {
    @ApiModelProperty(value = "账号")
    private String username;
    @ApiModelProperty(value = "密码")
    private String password;
}
复制代码

2.3 @ApiModelProperty

@ApiModelProperty() 用于字段，表示对 model 属性的说明

package com.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@Data
@ApiModel(value = "com.pojo",description = "用户pojo")
public class User {
    @ApiModelProperty(value = "账号")
    private String username;
    @ApiModelProperty(value = "密码")
    private String password;
}
复制代码

2.4 @ApiParam

@ApiParam 用于 Controller 中方法的参数说明

value：参数说明
required：是否必填

@RestController
@RequestMapping("/api")
@Api(tags = "测试swagger接口",description = "User模块")//描述
public class SwaggerController {
    @ApiOperation(value = "我的第一个swagger接口")
    @PostMapping("/swagger")
    public User testUser(@ApiParam(value = "用户实体",required = true) @RequestBody User user, HttpServletRequest request){
        System.out.println(request.getHeader("token"));
        return user;
    }
}
复制代码

2.5 @ApiOperation

@ApiOperation 用在 Controller 里的方法上，说明方法的作用，每一个接口的定义

value：接口名称

@RestController
@RequestMapping("/api")
@Api(tags = "测试swagger接口",description = "User模块")//描述
public class SwaggerController {
    @ApiOperation(value = "我的第一个swagger接口")
    @PostMapping("/swagger")
    public User testUser(@ApiParam(value = "用户实体",required = true) @RequestBody User user, HttpServletRequest request){
        System.out.println(request.getHeader("token"));
        return user;
    }
}
复制代码

2.6 @ApiResponse 和 @ApiResponses

@ApiResponse 用于方法上，说明接口响应的一些信息；@ApiResponses 组装了多个 @ApiResponse

@GetMapping("/getUser")
    @ApiOperation(value = "获取用户信息接口")
    @ApiResponses({ @ApiResponse(code = 0, message = "相应成功", response = SysUser.class) })
    public SysUser getUserInfo(@ApiParam(value = "用户id",required = true) @RequestParam String id){
        return userService.getUserInfo(id);
    }
复制代码

2.7 @ApiImplicitParam 和 @ApiImplicitParams

用于方法上，为单独的请求参数进行说明

@GetMapping("/getUser")
    @ApiOperation(value = "获取用户信息接口")
    @ApiResponses({ @ApiResponse(code = 0, message = "相应成功", response = SysUser.class) })
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户id", dataType = "string", paramType = "query", 
required = true, defaultValue = "0f09e661-7e80-4e1b-b66a-2e266bb593bf")
    })
    public SysUser getUserInfo(@ApiParam(value = "用户id",required = true) @RequestParam String id){
        return userService.getUserInfo(id);
    }
复制代码

3. 引入Swagger的jar

<!--swagger2 依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
        </dependency>
复制代码

4. 创建Swagger的配置类

package com.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
import java.util.List;
@Configuration//表示这是一个配置类
@EnableSwagger2//开启Swagger2
public class SwaggerConfig {
    @Bean
    public Docket reeateDocket(){
        List<Parameter> parameterList=new ArrayList<>();
        ParameterBuilder parameterBuilder=new ParameterBuilder();
        parameterBuilder.name("token")
                        .description("swagger调试用，模拟传入用户凭证")
                        .modelRef(new ModelRef("String"))
                        .parameterType("header").required(false);
        parameterList.add(parameterBuilder.build());
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//创建该Api的基本信息（这些基本信息会展现在文档页面中）
                .select()//函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger ui来展现
                .apis(RequestHandlerSelectors.basePackage("com.controller"))//指定需要扫描的包路路径
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(parameterList)
                ;
    }
    //配置swagger的信息
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("spring boot2.x实战")
                .description("整合swagger")
                .termsOfServiceUrl("")
                .version("2.0")
                .build();
    }
}
复制代码

5. 实体类创建

package com.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@Data
@ApiModel(value = "com.pojo",description = "用户pojo")
public class User {
    @ApiModelProperty(value = "账号")
    private String username;
    @ApiModelProperty(value = "密码")
    private String password;
}
复制代码

6. 测试类创建

package com.controller;
import com.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.http.HttpRequest;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import javax.servlet.http.HttpServletRequest;
@RestController
@RequestMapping("/api")
@Api(tags = "测试swagger接口",description = "User模块")//描述
public class SwaggerController {
    @ApiOperation(value = "我的第一个swagger接口")
    @PostMapping("/swagger")
    public User testUser(@ApiParam(value = "用户实体",required = true) @RequestBody User user, HttpServletRequest request){
        System.out.println(request.getHeader("token"));
        return user;
    }
}
复制代码

7. 测试

在浏览器上输入：http://localhost:8080/swagger-ui.html