官网
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
<!-- 引入swagger3包 -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version>
</dependency>
配置类
SwaggerConfig.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.htmlprivate static final String basePackage = "com.lm.system";@Beanpublic 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
<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
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();}@Overridepublic 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
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
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
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
<!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>
效果图
项目目录结构
