SpringBoot整合Swagger-CSDN博客

本文链接：https://blog.csdn.net/m0_37911706/article/details/125279136

一、Swagger简介

随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了前后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。前端和后端的唯一联系，变成了 API 接口，所以 API 文档变成了前后端开发人员联系的纽带，变得越来越重要。

那么问题来了，随着代码的不断更新，开发人员在开发新的接口或者更新旧的接口后，由于开发任务的繁重，往往文档很难持续跟着更新，Swagger 就是用来解决该问题的一款重要的工具，对使用接口的人来说，开发人员不需要给他们提供文档，只要告诉他们一个 Swagger 地址，即可展示在线的 API 接口文档，除此之外，调用接口的人员还可以在线测试接口数据，同样地，开发人员在开发接口时，同样也可以利用 Swagger 在线接口文档测试接口数据，这给开发人员提供了便利。

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化Restful风格的web服务。

二、Swagger作用：

1、接口的文档在线自动生成

2、功能测试

三、Swagger常用注解：

@Api ：可以用来标记 Controller 的功能

@ApiOperation：用来标记一个方法的作用

@ApilmplicitParam：用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入

@ApilmplicitParams：如果有多个参数，则需要使用多个 @ApilmplicitParam 注解来描述，多个 @ApilmplicitParam 注解需要放在一个 @ApilmplicitParams 注解中

@ApiModel ：如果参数是一个对象，则需要在对象所在的类上加上此注解

@ApiModelProperty ：如果参数是一个对象，则需要在对应的属性上加上此注解，还需要在对象所在的类上加上 @ApiModel

@ApiIgnore：注解标识此参数可以忽略

四、SpringBoot整合Swagger

1、引入依赖

<!--配置swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.1</version>
</dependency>

注意： Swagger的访问页面是swagger-ui.html；加入如下依赖可以让Swagger的页面更清晰、更漂亮

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.6</version>
</dependency>

加入以上依赖后Swagger的访问页面为doc.html

2、在application.yml中添加配置

#配置Swagger
swagger:
  basePackage: com.swa.swaggerdemo.controller #Controller所在的包
  title: Swagger测试 #Swagger文档标题
  description: 首次使用Swagger #详细描述
  version: V1.0 #版本号

3、添加swagger配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Value("${swagger.basePackage}")
    private String basePackage;  //controller所在的包
    @Value("${swagger.title}")
    private String title;//当前文档的标题
    @Value("${swagger.description}")
    private String description;//当前文档的详细描述
    @Value("${swagger.version}")
    private String version; //当前文档的版本

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()) //指定构建api文档的详细信息的方法：apiInfo()
                .select()
                //指定要生成api接口的包路径，这里把controller作为包路径，生成controller中的所有接口
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .paths(PathSelectors.any())
                .build();
    }
    /*
      构建api文档的详细信息
     */
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title(title) //设置标题
                .description(description) //设置接口描述
                .version(version) //设置版本
                .build();
    }
}

4、创建Controller

@Api(value = "测试用控制器")
@RestController
public class SwaggerTestController {
    @ApiOperation(value = "测试接口")
    @GetMapping("/hello")
    public String hell(){
        return "I Love You";
    }

5、测试

启动项目，访问地址：

http://localhost:端口号/项目名称/swagger-ui.html

当然，也有很多spring boot的项目是没有项目名称的，

http://localhost:端口号/swagger-ui.html

本项目的地址是 http://localhost:8080/swagger-ui.html

若访问清晰漂亮的页面，输入地址：http://localhost:8080/doc.html

6、带参数测试

(1)添加Controller

@ApiOperation(value = "测试参数传递")
@ApiImplicitParam(name = "pid", value = "商品id", required = true, dataType = "Integer", paramType = "path")
@PostMapping("/params/{pid}")
public String findById(@PathVariable("pid") Integer pid){
    return "您输入的书号是："+pid;
}

（2）测试