【SpringBoot】5 Swagger

枫叶_v2024-07-27 12:45

官网

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>

效果图


项目目录结构

相关推荐
Theodore_10222 小时前
4 设计模式原则之接口隔离原则
java·开发语言·设计模式·java-ee·接口隔离原则·javaee
冰帝海岸3 小时前
01-spring security认证笔记
java·笔记·spring
世间万物皆对象3 小时前
Spring Boot核心概念：日志管理
java·spring boot·单元测试
没书读了4 小时前
ssm框架-spring-spring声明式事务
java·数据库·spring
小二·4 小时前
java基础面试题笔记（基础篇）
java·笔记·python
开心工作室_kaic4 小时前
ssm161基于web的资源共享平台的共享与开发+jsp(论文+源码)_kaic
java·开发语言·前端
懒洋洋大魔王4 小时前
RocketMQ的使⽤
java·rocketmq·java-rocketmq
武子康4 小时前
Java-06 深入浅出 MyBatis - 一对一模型 SqlMapConfig 与 Mapper 详细讲解测试
java·开发语言·数据仓库·sql·mybatis·springboot·springcloud
qq_17448285755 小时前
springboot基于微信小程序的旧衣回收系统的设计与实现
spring boot·后端·微信小程序
转世成为计算机大神5 小时前
易考八股文之Java中的设计模式？
java·开发语言·设计模式
热门推荐
01(欧拉)openEuler系统添加网卡文件配置流程、(欧拉)openEuler系统手动配置ipv6地址流程、(欧拉)openEuler系统网络管理说明02PyTorch机器学习实现液态神经网络03【HarmonyOS】HUAWEI DevEco Studio 下载地址汇总04玄机平台应急响应—webshell查杀05Coze扣子平台完整体验和实践（附国内和国际版对比）06Ubuntu 20.04使用Livox mid 360 测试 FAST_LIO07【目标跟踪】相机运动补偿08Unity中PICO实现 隔空取物 和 接触抓取物体09RAG 实践- Ollama+RagFlow 部署本地知识库10怎样让音频速度变慢？请跟随以下方法进行操作