【SpringBoot】5 Swagger

官网

https://swagger.io/

介绍

Swagger 是一套基于 OpenAPI 规范构建的开源工具，可以帮助开发者实现设计、构建、记录、使用 Rest API。

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

Swagger主要包括三部分：

Swagger Editor：基于浏览器的编辑器，开发者可以使用它来编写我们的 OpenAPI 文档。
Swagger UI：它会将开发者编写的 OpenAPI 规范呈现为交互式的 API 文档。
Swagger CodeGen：它可以通过为 OpenAPI 规范定义的任何 API 生成服务器存根和客户端 SDK 来简化构建过程。

用处：

后端
- 不用再厚些 WiKi 接口拼接大量参数，避免手写出现的错误。
- 对代码侵入性低，采用注解的方式，开发简单。
- 方法参数名修改、增加、减少参数都可以直接生效，不用再手动进行维护。
- 缺点：增加开发成本，写接口需要再写一套参数配置。
前端
- 后端只需要定义好接口，swagger会自动生成文档，接口功能、参数一目了然。
- 联调方便，如果出现问题，可以直接测试接口，实时检查参数和返回值，可以快速定位是前端还是后端的问题。
测试
- 对于某些没有前端界面 UI 功能，可以用它来测试接口。
- 操作简单，不用了解具体代码就可以进行操作。

依赖

pom.xml

xml 复制代码

<!-- 引入swagger3包 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

配置类

SwaggerConfig.java

java 复制代码

package com.lm.system.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.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.Collections;
import java.util.List;

/**
 * @Author: DuHaoLin
 * @Date: 2024/7/26
 */
@Configuration
public class SwaggerConfig {

//访问地址： http://localhost:8888/swagger-ui/index.html

    private static final String basePackage = "com.lm.system";

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                //设置API文档的基本信息
                .apiInfo(apiInfo())
                //进入API选择器的配置
                .select()
                //设置API选择器的基本包路径，表示只选择该包及其子包中的API进行文档生成。
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                //设置API选择器的路径选择器，表示选择所有路径的API进行文档生成。
                .paths(PathSelectors.any())
                .build()
                //小按钮进行方法的调用
                .securitySchemes(Collections.singletonList(securityScheme()))
                .securityContexts(Collections.singletonList(securityContext()));
    }
    
    //这个是swagger页面中的一个小按钮，可以用来放token。
    //定义API的安全方案
    private SecurityScheme securityScheme() {
        //return new ApiKey("Authorization", "Authorization", "header");
        //创建一个ApiKey对象，传入三个参数，分别为密钥的名称、密钥的描述和认证方式。
        //这里的密钥名称和描述都设置为X-Token，认证方式为header，表示在请求的Header中进行认证。
        return new ApiKey("X-Token", "X-Token", "header");
    }
    
    //定义API的安全上下文。
    private SecurityContext securityContext() {
        return SecurityContext.builder()
                .securityReferences(defaultAuth())  //设置安全上下文的安全引用
                .forPaths(PathSelectors.regex("^(?!auth).*$"))  //设置安全上下文的路径选择器.除了以/auth开头的路径外，所有路径都需要进行安全认证
                .build();
    }
    
    //用于定义API的安全引用
    private List<SecurityReference> defaultAuth() {
        //授权范围的名称设置为global,描述设置为accessEverything，表示具有全局访问权限
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        //将前面创建的authorizationScope对象赋值给数组的第一个元素。
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        //认证方案的名称设置为X-Token.授权范围的数组为前面创建的authorizationScopes数组。
        return Collections.singletonList(
                new SecurityReference("X-Token", authorizationScopes));
    }

    //一些swagger的信息配置
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //接口标题名
                .title("System接口文档")
                //接口描述
                .description("")
                //版本
                .version("1.0")
                //作者信息
                .contact(new Contact("ldh", "https://www.baidu.com", "ldh_dev@163.com"))
                .build();
    }

}

统一返回结果

依赖

pom.xml

xml 复制代码

<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.20</version>
    <optional>true</optional>
</dependency>

<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.8.9</version>
</dependency>

返回结果类

ResultBody.java

java 复制代码

package com.lm.system.common;

import com.google.gson.*;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.experimental.Accessors;
import lombok.extern.slf4j.Slf4j;
import org.springframework.http.HttpEntity;
import org.springframework.http.HttpStatus;

import javax.servlet.http.HttpServletResponse;
import java.io.Serializable;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.ZoneId;
import java.time.format.DateTimeFormatter;
import java.util.Collection;
import java.util.Map;

/**
 * @Author: DuHaoLin
 * @Date: 2024/7/26
 */
 
@Data
@Slf4j
@Accessors(chain = true)
@AllArgsConstructor
public class ResultBody<T> implements Serializable {

    private static final long serialVersionUID = 1L;

    @ApiModelProperty("状态码: 404")
    private long status;
    @ApiModelProperty("返回信息")
    private String msg;
    @ApiModelProperty("数据总数")
    private long count;
    @ApiModelProperty("返回数据")
    private T data;

    public static final Gson GSON;

    static {
        final JsonSerializer<LocalDateTime> localDateTimeJsonSerializer = (src, typeOfSrc, context) ->
                new JsonPrimitive(src.withNano(0).atZone(ZoneId.systemDefault()).format(DateTimeFormatter.ISO_LOCAL_DATE_TIME));

        final JsonSerializer<LocalDate> localDateJsonSerializer = (src, typeOfSrc, context) ->
                new JsonPrimitive(src.format(DateTimeFormatter.ISO_LOCAL_DATE));

        GSON = new GsonBuilder()
                .serializeNulls() //包括空参
                .setPrettyPrinting() //格式化
                .registerTypeAdapter(LocalDateTime.class, localDateTimeJsonSerializer) //类型适配器
                .registerTypeAdapter(LocalDate.class, localDateJsonSerializer) //类型适配器
                .setDateFormat("yyyy-MM-dd HH:mm:ss") //日期格式
                .disableHtmlEscaping() //禁用Http转义
                .setFieldNamingPolicy(FieldNamingPolicy.LOWER_CASE_WITH_UNDERSCORES) //小写下划线
                .create();
    }

    @Override
    public String toString() {
        return getReturn();
    }

    private ResultBody() {}

    public static <T> ResultBody<T> build() {
        return createResponse(0, null);
    }

    public static <T, V extends Collection<T>> ResultBody<V> build(V collection) {
        return createResponse(collection.size(), collection);
    }

    public static <T, R> ResultBody<Map<T, R>> build(Map<T, R> map) {
        return createResponse(map.size(), map);
    }

    public static <T> ResultBody<T> build(T map) {
        if (map == null) return build();
        return createResponse(1, map);
    }

    public static <T> ResultBody<T> build(HttpStatus status) {
        return new ResultBody<T>().setStatus(status.value());
    }

    private static <T> ResultBody<T> createResponse(long size, T data) {
        ResultBody<T> resultBody;
        if (size == 0) {
            resultBody = build(HttpStatus.NO_CONTENT);
        } else {
            resultBody = build(HttpStatus.OK);
            resultBody.count = size;
        }
        resultBody.data = data;
        return resultBody;
    }

    public String getReturn() {
        String json = GSON.toJson(this);
        log.info(json);
        return json;
    }

}

接口

将 Usercontroller 改为 UserPageController 。

新建 UserController 类。

UserPageController.java

java 复制代码

package com.lm.system.controller;

import com.lm.system.common.User;
import io.swagger.annotations.Api;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;

/**
 * @Author: DuHaoLin
 * @Date: 2024/7/26
 */
@Controller
@Api(tags = "用户页面")
public class UserPageController {

    @GetMapping("userPage")
    public String user(Model model) {
        User user = User.builder()
                .name("Tom")
                .age(18)
                .gender(0)
                .build();
        model.addAttribute("user", user);
        return "user";
    }

}

User.java

java 复制代码

package com.lm.system.common;

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

import java.time.LocalDateTime;

/**
 * @Author: DuHaoLin
 * @Date: 2024/7/26
 */
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@ApiModel("用户实体类")
public class User {

    private Integer id;
    private String name;
    private Integer age;
    private Integer gender; //性别：0男，1女
    private LocalDateTime createTime;
    private LocalDateTime updateTime;

    private Integer deleted; //是否已经删除：0否，1是
    
}

UserController.java

java 复制代码

package com.lm.system.controller;

import com.lm.system.common.ResultBody;
import com.lm.system.common.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.HttpStatus;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

import java.time.LocalDateTime;
import java.util.Objects;

/**
 * @Author: DuHaoLin
 * @Date: 2024/7/26
 */
@RestController
@Api(tags = "用户接口")
public class UserController {

    @GetMapping("user")
    @ApiOperation("获取用户信息")
    public String user() {
        User user = User.builder()
                        .name("Tom")
                        .age(18)
                        .gender(0)
                        .build();
        return ResultBody
                .build(HttpStatus.OK)
                .setData(user)
                .setCount(1)
                .getReturn();
    }

}

user.html

html 复制代码

<!DOCTYPE html>
<html lang="en" xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>Thymeleaf</title>
</head>
<body>
    <span>姓名:</span>
    <span th:text="${user.name}"></span>
    <br />
    <span>年龄:</span>
    <span th:text="${user.age}"></span>
    <br />
    <span>性别:</span>
    <span th:text="${user.gender} == 0 ? '男' : '女'"></span>
</body>
</html>

【SpringBoot】5 Swagger

官网

介绍

依赖

配置类

统一返回结果

依赖

返回结果类

接口

效果图

项目目录结构