天行健，君子以自强不息；地势坤，君子以厚德载物。

---

每个人都有惰性，但不断学习是好好生活的根本，共勉！

---

文章均为学习整理笔记，分享记录为主，如有错误请指正，共同学习进步。

---

Swagger2简介

swagger2是一个基于OpenAPI（OpenAPI Specification，OAS）构建的开源工具，提供对REST API文档的一些有效帮助。简而言之就是将项目中的controller类和方法通过注解方式生成文档展现出来。
swagger包含三个内容：

• swagger codegen：通过OpenApi规范定义任何api生成服务器存根和客户端sdk来简化构建过程
• swagger editor： 浏览器编辑器，用来编写OpenApi规范
• swagger ui： 可以在浏览器上查看并操作REST API

两个组件：

• springfox-swagger2： 这个组件用于自动生成描述API的json文件
• springfox-swagger-ui： 将描述API的json解析并展现

下面介绍的就是2.9.2版本

---

开发环境：

JDK版本：1.8
maven版本：3.9.0
开发工具：IDEA社区版ideaIC-2018.3
项目框架：spring boot 版本为 2.3.4.RELEASE springboot搭建传送门

实现步骤说明

1. 搭建项目

创建maven项目引入springboot依赖
项目包框架如下
注：这里使用2.9.2版本的swagger，需要配置Swagger2Config配置类

2. 引入依赖

引入spring boot和swagger2依赖
注：这里可能因为版本兼容问题，我试了很多个版本都会出现报错，目前来看2.3.4.RELEASE版本是可以和swagger的2.9.2版本配合使用的

<dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
            <version>2.3.4.RELEASE</version>
        </dependency>

        <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>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.26</version>
        </dependency>

3. 创建启动类

SwaggerApplication.java

package com.swagger;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * @ClassDescription:
 * @Author：李白
 * @Date：2023/5/22 14:57
 */
@SpringBootApplication
public class SwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class, args);
    }
}

4. Swagger配置类

Swagger2Config.java
配置了一些定制参数

package com.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @ClassDescription:
 * @Author：李白
 * @Date：2023/5/22 16:18
 */

@Configuration
@EnableSwagger2 //开启swagger2
public class Swagger2Config {


    /**
     * 创建RESTFUL API文档内容
     * @return
     */
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                //此处参数为ApiInfo对象
                //指定构建api文档的详细信息的方法
                .apiInfo(apiInfo())
                .select()
                //指定构建api接口的包路径-指定具体包路径
//                .apis(RequestHandlerSelectors.basePackage("com.provider.controller"))
                //指定构建api接口的包路径-此处为所有包（未指定）
                .apis(RequestHandlerSelectors.any())
                //访问路径下面的接口
//                .paths(PathSelectors.any())
//                .paths(PathSelectors.ant("/libai/**"))
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //可根据url路径设置那些请求加入文档，忽略哪些请求
                .paths(PathSelectors.any())
                .build()
                //分组管理可以与哪个访问路径结合使用
//                .groupName("用户管理")
                ;
    }

    /**
     * 创建API界面的基本信息
     * @return 返回一个构建好的ApiInfo对象
     */
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                //界面标题
                .title("Swagger2构建Restful API文档")
                //接口描述
                .description("后端API接口文档展示")
                //联系方式，联系人-网址-邮箱
                .contact(new Contact("libai","https://github.com/libai","libai@163.com"))
                //版本信息
                .version("1.0.0")
                //证书描述
                .license("访问主页")
                //证书地址
                .licenseUrl("https://www.baidu.com")
                //系统服务网址
                .termsOfServiceUrl("http://gitgub.com/libai")
                //以上全部，开始构建
                .build();
    }
}

5. 创建实体类

UserInfo.java

package com.swagger.entity;

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

/**
 * @ClassDescription:
 * @Author：李白
 * @Date：2023/5/22 16:00
 */
@ApiModel(value = "用户实体类", description = "用户实体类描述")
@Data
@NoArgsConstructor
@AllArgsConstructor
public class UserInfo {
    @ApiModelProperty(name = "id", value = "学生姓名", example = "12345")
    private Integer id;
    @ApiModelProperty(name = "username", value = "用户账号", example = "12345")
    private String username;
    @ApiModelProperty(name = "password", value = "用户密码", example = "12345")
    private String password;
}

6. 返回包装类

ResponseResult.java

package com.swagger.vo;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import java.io.Serializable;

/**
 * @ClassDescription: 返回结果集
 * @Author：李白
 * @Date：2023/5/20 13:58
 */
@Data
@NoArgsConstructor
@AllArgsConstructor
public class ResponseResult implements Serializable {
    private Integer code;
    private String message;
    private Object result;

    public static ResponseResult success(){
        ResponseResult responseResult = new ResponseResult();
//        responseResult.setResult(result);
        responseResult.setCode(200);
        responseResult.setMessage("success");
        return responseResult;
    }

    public static ResponseResult success(Object result){
        ResponseResult responseResult = new ResponseResult();
        responseResult.setResult(result);
        responseResult.setCode(200);
        responseResult.setMessage("success");
        return responseResult;
    }

}

7. 创建控制类

UserController.java

package com.swagger.controller;

import com.swagger.entity.UserInfo;
import com.swagger.vo.ResponseResult;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

/**
 * @ClassDescription:
 * @Author：李白
 * @Date：2023/5/22 15:01
 */
@Api(value = "用户数据操作类",tags = {"用户数据操作接口"})
@RestController
@RequestMapping("/user")
public class UserController {

    /**
     * 模拟数据库
     */
    static Map<Integer, UserInfo> users = new HashMap<>();

    /**
     * 模拟自增主键
     */
    static Integer id = 1;

    /**
     * 查询所有数据
     * @return
     */
    @ApiOperation(value = "查询用户数据", notes = "查询所有用户数据")
    @GetMapping
    public ResponseResult getUserInfoList(){
        List<UserInfo> userInfoList = new ArrayList<>(users.values());
        return ResponseResult.success(userInfoList);
    }

    /**
     * 根据id查询数据
     * @param id
     * @return
     */
    @ApiOperation(value = "根据id查询数据", notes = "根据id查询数据信息")
//    @ApiParam(name = "id", value = "用户id", required = true)
//    @ApiImplicitParam(name = "id", value = "用户id", dataType = "Integer", paramType = "query",example = "libai123", required = true)
    @GetMapping("/{id}")
    public ResponseResult getUserInfoById(@PathVariable("id") Integer id){
        return ResponseResult.success(users.get(id));
    }

    /**
     * 新增数据
     * @param userInfo
     * @return
     */
//    @ApiIgnore//用在类或方法上，可以不被swagger显示在页面上
//    @ApiResponses({@ApiResponse(code = 200, message = "ok", response = UserInfo.class)})
    @ApiOperation(value = "新增数据", notes = "新增用户数据信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", required = true),
            @ApiImplicitParam(name = "password", value = "用户密码", required = true)
    })
    @PostMapping
    public ResponseResult postUserInfo(UserInfo userInfo){
        userInfo.setId(id++);
        users.put(userInfo.getId(),userInfo);
        System.out.println(users);
        return ResponseResult.success();
    }

    /**
     * 更新数据
     * @param userInfo
     * @return
     */
    @ApiOperation(value = "更新数据", notes = "更新用户数据")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", required = true),
            @ApiImplicitParam(name = "password", value = "用户密码", required = true)
    })
    @PutMapping
    public ResponseResult putUserInfo(UserInfo userInfo){
        UserInfo userInfo1 = users.get(userInfo.getId());
        userInfo1.setPassword(userInfo.getPassword());
        userInfo1.setUsername(userInfo.getUsername());
        return ResponseResult.success(userInfo1);
    }

    /**
     * 删除数据
     * @param id
     * @return
     */
    @ApiOperation(value = "删除数据", notes = "根据id删除用户数据")
    @ApiImplicitParam(name = "id", value = "用户id", required = true)
    @DeleteMapping("/{id}")
    public ResponseResult deleteUserInfo(@PathVariable("id") Integer id){
        users.remove(id);
        return ResponseResult.success();
    }




}

7. 添加swagger2相关注解

在实体类和控制类上添加相应的注解
注解介绍如下：

• 在配置类上添加注解@EnableSwagger2开启swagger
• 在controller类上添加@Api
• 在实体类上添加@ApiModel
• 实体类（对象）属性添加@ApiModelProperty
• 接口参数描述使用@ApiImplicitParams
• 接口响应使用@ApiResponses
• 接口忽略（可不在网页中显示）使用@ApiIgnore

8. 查看生成的文档

启动项目
浏览器中访问地址（端口号可根据自己的项目端口更改，默认为8080）

http://localhost:8080/swagger-ui.html

（2.9.2版本为上面这个地址，3.0.0的新版本则为http://localhost:8080/swagger-ui/index.html）
如下图

---