Spring Boot2集成Swagger框架

你吃了吗c

于 2024-04-28 10:55:07 发布

阅读量1.4k

点赞数 45

分类专栏：学习笔记文章标签： spring boot 后端

本文链接：https://blog.csdn.net/username00000/article/details/138271098

版权

学习笔记专栏收录该内容

13 篇文章 0 订阅

订阅专栏

引言

无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精

力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱

怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。

一、swagger介绍

1.swagger介绍及作用

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

Swagger是一个接口文档生成工具，同时提供接口测试调用的辅助功能。它可以将项目的所有接口在一个UI界面上展示出来，同时表明了这个接口的用途，接口需要的参数是什么类型参数是否必须，输入了参数可以直接测试接口同时会显示接口请求的状态码和返回的数据结构。

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试软件。也是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。

swagger是一款可以根据Resutful风格生成的接口开发文档，并且支持做测试的一款中间软件。

2.swagger优点

Swagger能成为最受欢迎的Resutful风格文档生成工具之一，有以下几个原因：

Swagger 可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API。
大大减少前后端的沟通成本，方便查找和测试接口
提高团队的开发效率
方便新人了解项目

3.Spring Boot2集成swagger步骤

3.1新建springboot项目

3.2 添加依赖

<!--swagger2核心依赖-->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>

<!-- swagger-ui为项目提供api展示及测试的界面-->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

3.3编写Controller

3.4 创建配置类

添加config包，创建SwaggerConfig自定义的类，添加注解

@Configuration   //添加配置
@EnableSwagger2  //开启
public class SwaggerConfig {
    
}

4.配置swagger

配置swagger，就需要创建 Bean实例Docket

@Bean
public Docket customDocket() {
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}

//配置appInfo
private ApiInfo apiInfo(){
    return new ApiInfo("Api Documentation",
                       "Api Documentation",
                       "1.0",
                       "urn:tos",
                       new Contact("", "", ""),
                       "Apache 2.0",
                       "http://www.apache.org/licenses/LICENSE-2.0",
                       new ArrayList());
}

访问：http://localhost:8080/swagger-ui.html

5.配置API文档分组

@Bean
public Docket customDocket() {
    return new Docket(
    DocumentationType.SWAGGER_2)
    .apiInfo(apiInfo())
    .groupName("项目一组")
    .select()
    .apis(RequestHandlerSelectors.basePackage("cn.hxzy.controller"))
    .build();
}

配置多个Docket实例即可

6.常用注解及配置扫描接口

swagger2是通过扫描很多的注解来获取数据帮我们展示在ui界面上的，下面就介绍下常用的注解。

1、@ApiModel()：用于响应实体类上，用于说明实体作用

参数：

description="描述实体的作用"

只要接口中，返回值中存在实体类，就会被扫描到swagger中

2、@ApiModelProperty：用在属性上，描述实体类的属性

参数：

value="用户名"     描述参数的描述文本
name="name"       参数的变量名
required=true     参数是否必选

3、@Api()：用在请求的类（controller）上，表示对类的说明，也代表了这个类是swagger2的资源

description

参数：

tags：说明该类的作用，参数是个数组，可以填多个。
value="该参数没什么意义，在UI界面上不显示，所以不用配置"
description = "用户基本信息操作"

4、@ApiOperation()：用于方法，表示一个http请求访问该方法的操作

参数：

value="方法的用途和作用"    
notes="方法的注意事项和备注"    
tags：说明该方法的作用，参数是个数组，可以填多个。
格式：tags={"作用1","作用2"} 
（在这里建议不使用这个参数，会使界面看上去有点乱，前两个常用）

5、@ApiParam()：用于方法参数，字段说明表示对参数的要求和说明【单个参数描述】

6、@ApiImplicitParams：用在请求的方法上，包含多@ApiImplicitParam 【多个参数描述】

7、@ApiImplicitParam：用于方法，表示单独的请求参数

参数：

name="参数名称"
value="参数的简要说明"
defaultValue="参数默认值"
required=true 表示属性是否必填，默认为false

示例

@ApiImplicitParams({
    @ApiImplicitParam(name = "userNo",
                      value = "用户账户",
                      defaultValue = "admin",
                      required = true),
    @ApiImplicitParam(name = "userPwd",
                      value = "用户密码",
                      defaultValue = "123",
                      required = true),
})

8、@ApiResponses：用于请求的方法上，根据响应码表示不同响应

一个@ApiResponses包含多个@ApiResponse

9、@ApiResponse：用在请求的方法上，表示不同的响应

参数：

code="404"    表示响应码(int型)，可自定义
message="状态码对应的响应信息"

示例

@ApiResponses({
    @ApiResponse(code = 10001,message = "用户积分不足"),
    @ApiResponse(code = 10002,message = "用户已欠费")
})

10、@ApiIgnore()：用于类或者方法上，不被显示在页面上，当作用在方法上时，方法将被忽略；作用在类上时，整个类都会被忽略；作用在参数上时，单个具体的参数会被忽略。

11、@Profile({“dev”, “test”})：用于配置类上，表示只对开发和测试环境有用

@Profile注解标识，@Profile({“dev”,“test”})表示在dev和test环境才能访问swagger-ui.html，prod环境下访问不了。

7.接口示例

1、根据ID删除

@ApiOperation(value = "删除用户信息")
@DeleteMapping("/delUserInfo/{userId}/{userName}")
@ApiResponses({
    @ApiResponse(code = 20000, message = "删除成功"),
    @ApiResponse(code = 20001, message = "删除失败")
})
@ApiImplicitParams({
    @ApiImplicitParam(name = "userId", value = "用户编号", defaultValue = "1", dataType = "Integer"),
    @ApiImplicitParam(name = "userName", value = "用户姓名",  dataType = "String")
})
public R delUserInfo(@PathVariable("userId") Integer userId,@PathVariable(name = "userName",required = false) String userName) {
    if (!StringUtils.isEmpty(userId)) {
        Integer count = userInfoService.delUserInfo(userId);
        if (count > 0) {
            return R.ok();
        } else {
            return R.error();
        }
    }
    return R.error();

}

2、无参查询全部数据

@ApiOperation(value = "查询用户信息", notes = "必须使用Get请求")
@GetMapping("/getUserInfo")
@ApiResponses({
    @ApiResponse(code = 20000, message = "查询成功"),
    @ApiResponse(code = 20001, message = "查询失败")
})
public R getUserInfo() {
    List<UserInfo> userInfo = userInfoService.getUserInfo();
    if (userInfo.size() > 0) {
        return R.ok().data("item", userInfo);
    } else {
        return R.error().data("item", null);
    }

}

3、保存实现对象入参

@PostMapping("/save")
@ApiResponses({
    @ApiResponse(code = 20000, message = "注册成功"),
    @ApiResponse(code = 20001, message = "注册失败")
})
@ApiImplicitParams({
    @ApiImplicitParam(name = "UserInfo", value = "用户信息"),
})
public R saveUserInfo(@RequestBody UserInfo userInfo){
    System.out.println(userInfo);
    return R.ok();
}

4、实体类

package cn.hxzy.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
@ApiModel("用户基本信息")
public class UserInfo {
    @ApiModelProperty(value="用户编号", name = "userId",required=true, dataType = "Integer")
    private Integer userId;
    @ApiModelProperty(value="用户名",name = "userName",required=true)
    private String userName;
    @ApiModelProperty(value="性别",name = "sex",required=false)
    private Integer sex;
    @ApiModelProperty(value="身份证",name = "card",required=true)
    private String card;
    @ApiModelProperty(value="手机号",name = "phone",required=true)
    private String phone;
    @ApiModelProperty(value="头像",name = "picPath",required=false)
    private String picPath;
}

8.swagger解决了什么

其实归根到底，使用Swagger，就是把相关的信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。

而Springfox-swagger,则可以通过扫描代码去生成这个描述文件，连描述文件都不需要再去维护了。所有的信息，都在代码里面了。代码即接口文档，接口文档即代码。

对于后端开发人员来说

不用再手写接口拼大量的参数，避免手写错误

对代码侵入性低，采用全注解的方式，开发简单

方法参数名修改、增加、减少参数都可以直接生效，不用手动维护

缺点：增加了开发成本，写接口还得再写一套参数配置
对于前端开发来说

后端只需要定义好接口，会自动生成文档，接口功能、参数一目了然

联调方便，如果出问题，直接测试接口，实时检查参数和返回值,就可以快速定位是前端还是后端的问题
对于测试

对于某些没有前端界面UI的功能，可以用它来测试接口

操作简单，不用了解具体代码就可以操作

你吃了吗c

关注

45
点赞
踩
51

收藏

觉得还不错? 一键收藏
0
评论
Spring Boot2集成Swagger框架

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

扫一扫