接口测试:Swagger的应用
1.从零建立一个项目及模块
项目结构如下
book #项目名称
–common #子模块
–domain #子模块
–book #子模块-业务模块
1.1新建项目
接下来利用idea分模块新建一个项目

基本不作修改,直接下一步

打开pom.xml文件,进行添加

添加完成后务必刷新
项目中的src文件夹如果没用可以删除
1.2 新建模块


直接创建完毕
按照以上步骤建立common,domain,test模块
在test模块中添加需要的依赖
<dependencies>
<dependency>
<groupId>top.satur.bookms.domain</groupId>
<artifactId>domain</artifactId>
<version>1.0-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>top.satur.bookms.common</groupId>
<artifactId>common</artifactId>
<version>1.0-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
<version>4.3.0</version>
</dependency>
</dependencies>
1.3 创建启动类
在test中创建启动类

1.4 创建4个application.xml
resources>config
–application.xml选择以下哪一项
–application-dev.xml本地开发环境
–application-prod.xml生产环境
–application-test.yml测试环境
输入以下内容
1.5创建响应类
问题: java泛型特点?—-泛型擦除
@Data
@NoArgsConstructor
@AllArgsConstructor
public class HttpResp<T> {
private int code; //响应码
private String msg; //响应信息
private T result; //返回结果
private LocalDate time; //返回时间
}
1.6 添加打包
在common和domain中,在pom.xml添加一下代码
<build>
<plugins>
<!-- 编译源代码插件 -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.0</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
<encoding>${project.build.sourceEncoding}</encoding>
</configuration>
</plugin>
<!-- 打包源代码插件 -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-source-plugin</artifactId>
<version>2.2.1</version>
<configuration>
<attach>true</attach>
</configuration>
<executions>
<execution>
<phase>compile</phase>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
在业务模块中,添加以下代码
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
2 Swagger的使用
添加依赖
<dependency><groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
<version>4.0.0</version>
</dependency>
在application.xml配置以下内容
knife4j:
enable: true #此项必配置,否则knife4j运行有问题
openapi:
title: knife4j项目的名称
description: knife4j项目的描述
email: 项目邮箱
concat: 贡献者名称
url: 项目的地址
license: Apache 2.0
license-url: http://www.apache.org/licenses/LICENSE-2.0
terms-of-service-url: 业务网址
2.1 常用注解
在返回对象上使用
在HttpResp(用户封装返回对象的类)
@ApiModel 用对象来接收参数
@ApiModelProperty 用对象接收参数时,描述对象的一个字段
在Controller类和方法上使用
@Api(tags = “Knife4jController接口类”)
@Api 修饰整个类,描述api(Controller)的作用
@ApiOperation 描述一个类的一个方法,或者说一个接口
@ApiImplicitParam 多个请求参数的描述信息
@ApiImplicitParam(name = “name”,value=”请求的名称”,required = true) 单个参数的描述信息
@ApiIgnore 使用该注解忽略这个API
@ApiError 发生错误返回的信息
ApiImplicitParm的属性
paramType 查询参数类型
path 以地址形式提交数据
query 直接跟参数完成映射赋值
body 以流的形式提交 仅支持POST
header 参数在request headers里面提交
form 以form表单的形式提交,仅支持POST
dataType 参数的数据类型 只为标志说明 并没有实际验证
Long
String
name 接收参数名
value 接收参数的意义描述
required 参数是否必填
true 必填
false 非比填
defaultValue 默认值
2.2 项目代码
controller
package top.satur.bookms.book.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;
import top.satur.bookms.common.result.HttpResp;
import top.satur.bookms.domain.entity.Type;
import java.time.LocalDateTime;
import java.util.ArrayList;
import java.util.List;
@RestController
@Api(tags = "图书类型接口")
@RequestMapping("/api/type")
@Slf4j
public class TypeController {
int total=0;
@GetMapping("/findAll")
@ApiOperation(value = "findAll", notes = "查找所有图书")
public HttpResp<Integer> findAll() {
List<Type> list = new ArrayList<>(100);
for (int i = 0; i < 99; i++) {
list.add(new Type(i, "bookname" + i, "ppg", LocalDateTime.now(), LocalDateTime.now()));
}total+=1;
log.debug("查询所有图书数量:{}", total);
return new HttpResp<>(200, "success", total, LocalDateTime.now());
}
@PostMapping("/addType")
@ApiOperation(value = "addType", notes = "插入图书")
@ApiImplicitParams(
{
@ApiImplicitParam(name = "name", value = "图书名称", required = true)
}
)
public HttpResp<String> addType(String name) {
log.debug("插入图书:{}", name);
return new HttpResp<>(200, "success", name, LocalDateTime.now());
}
@PostMapping("/uploadExcel")
@ApiOperation(value = "uploadExcel", notes = "上传excel文件进行解析")
@ApiImplicitParams(
{
@ApiImplicitParam(value = "上传文件", required = true)
}
)
public HttpResp<String> uploadExcel(@RequestPart @RequestParam("excel") MultipartFile excel) {
String originalFileName = excel.getOriginalFilename();
log.debug("上传文件名:{}", originalFileName);
return new HttpResp<>(200, "success", originalFileName + "上传成功", LocalDateTime.now());
}
}
common
package top.satur.bookms.common.result;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import java.time.LocalDateTime;
@Data
@NoArgsConstructor
@AllArgsConstructor
public class HttpResp<T> {
private Integer code;
private String msg;
private T data;
private LocalDateTime time;
}
domain
package top.satur.bookms.domain.entity;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import java.time.LocalDateTime;
@Data
@NoArgsConstructor
@AllArgsConstructor
public class Type {
private Integer id;
private String name;
private String createBy;
private LocalDateTime createTime;
private LocalDateTime updateTime;
}
本文详细介绍了如何在SpringBoot项目中从零开始构建模块,包括模块划分、添加依赖、创建启动类和配置Swagger。重点讲解了Java泛型和HttpResp类的使用,以及如何利用Swagger进行API文档生成和注解配置。



被折叠的 条评论
为什么被折叠?



