项目中遇到的错误
- swagger2 和 swagger3
- swagger 文档的注解
- springboot 版本问题
- SQL 关键字异常
- Apifox 的使用
- 集中版本管理
swagger2 和 swagger3
swagger2和 swagger3 需要导入的依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-configuration-processor</artifactId>
<optional>true</optional>
</dependency>
<!-- commons-lang3-->
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-lang3</artifactId>
<version>3.10</version>
</dependency>
swagger2访问地址 http://localhost/doc.html
swagger2 的配置类
@EnableSwagger2
@Configuration
public class SwaggerConfig {
/**
* 设置要暴露接口文档的配置环境
* @param env 环境
* @return Docket
*/
@Bean
public Docket initDocket(Environment env) {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()) .enable(true) .select()
.apis(RequestHandlerSelectors
.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any()) .build(); }
private ApiInfo apiInfo() { return new ApiInfoBuilder()
.title("图书管理系统") .description("管理书籍和读者信息，管理书籍，借阅和归还书籍")
.contact(new Contact("coffeemao", null, "123456@qq.com "))
.version("1.0") .build(); }
}
swagger3访问地址 http://localhost:8080/swagger-ui/index.html
// 开启 OpenApi
@EnableOpenApi
@Configuration
public class SwaggerConfig {
public Docket docket(){
Docket docket = new Docket(DocumentationType.OAS_30);
docket.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.mao.book.controller"))
.paths(PathSelectors.any()).build();
return docket;
}
private ApiInfo apiInfo(){
Contact contact = new Contact("作者 coffeemao", "作者www.baidu.com","123456@qq.com");
ApiInfo apiInfo = new ApiInfo(
"Swagger3接口文档",
"SpringBoot 整合 Swagger3 生成接口文档!",
"1.0.0",
"termsOfServiceUrl",
contact,
"license",
"licenseUrl",
new ArrayList());
return apiInfo;
}
}
或者使用以下更为灵活的自定义配置类
SwaggerProperties 的属性类
@Component
@ConfigurationProperties("swagger")
@Data
@AllArgsConstructor
@NoArgsConstructor
public class SwaggerProperties {
/**
* 是否开启swagger，生产环境一般关闭，所以这里定义一个变量
*/
private Boolean enable;
/**
* 项目应用名
*/
private String applicationName;
/**
* 项目版本信息
*/
private String applicationVersion;
/**
* 项目描述信息
*/
private String applicationDescription;
/**
* 接口调试地址
*/
private String tryHost;
}
自定义的配置类
@EnableOpenApi
@Configuration
public class SwaggerConfiguration implements WebMvcConfigurer {
private final SwaggerProperties swaggerProperties;
public SwaggerConfiguration(SwaggerProperties swaggerProperties) {
this.swaggerProperties = swaggerProperties;
}
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30).pathMapping("/")
// 定义是否开启swagger，false为关闭，可以通过变量控制
.enable(swaggerProperties.getEnable())
// 将api的元信息设置为包含在json ResourceListing响应中。
.apiInfo(apiInfo())
// 接口调试地址
.host(swaggerProperties.getTryHost())
// 选择哪些接口作为swagger的doc发布
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build()
// 支持的通讯协议集合
.protocols(newHashSet("https", "http"))
// 授权信息设置，必要的header token等认证信息
.securitySchemes(securitySchemes())
// 授权信息全局应用
.securityContexts(securityContexts());
}
/**
* API 页面上半部分展示信息
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title(swaggerProperties.getApplicationName() + " Api Doc")
.description(swaggerProperties.getApplicationDescription())
.contact(new Contact("coffeemao", null, "123456@gmail.com"))
.version("Application Version: " + swaggerProperties.getApplicationVersion() + ", Spring Boot Version: " + SpringBootVersion.getVersion())
.build();
}
/**
* 设置授权信息
*/
private List<SecurityScheme> securitySchemes() {
ApiKey apiKey = new ApiKey("BASE_TOKEN", "token", In.HEADER.toValue());
return Collections.singletonList(apiKey);
}
/**
* 授权信息全局应用
*/
private List<SecurityContext> securityContexts() {
return Collections.singletonList(
SecurityContext.builder()
.securityReferences(Collections.singletonList(new SecurityReference("BASE_TOKEN", new AuthorizationScope[]{new AuthorizationScope("global", "")})))
.build()
);
}
@SafeVarargs
private final <T> Set<T> newHashSet(T... ts) {
if (ts.length > 0) {
return new LinkedHashSet<>(Arrays.asList(ts));
}
return null;
}
/**
* 通用拦截器排除swagger设置，所有拦截器都会自动加swagger相关的资源排除信息
*/
@SuppressWarnings("unchecked")
@Override
public void addInterceptors(InterceptorRegistry registry) {
try {
Field registrationsField = FieldUtils.getField(InterceptorRegistry.class, "registrations", true);
List<InterceptorRegistration> registrations = (List<InterceptorRegistration>) ReflectionUtils.getField(registrationsField, registry);
if (registrations != null) {
for (InterceptorRegistration interceptorRegistration : registrations) {
interceptorRegistration
.excludePathPatterns("/swagger**/**")
.excludePathPatterns("/webjars/**")
.excludePathPatterns("/v3/**")
.excludePathPatterns("/doc.html");
}
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
applicaton.xml 对 swagger3 进行了开启，应用的应用名字，应用程序的版本信息，描述信息，访问的地址等
spring:
application:
name: 图书管理系统
swagger:
enable: true
application-name: ${spring.application.name}
application-version: 1.0
application-description: swagger3.0 的图书管理文档
try-host: http://localhost:${server.port}
swagger 文档的注解
@Api()用在请求的类上，表示对类的说明，在controller层的类上的注解
参数
tags：说明该类的作用，参数是个数组，可以填多个。
description = “用户基本信息操作”
@ApiOperation()用于方法，表示一个http请求访问该方法的操作，在controller层类的方法上的注解
参数
value=“方法的用途和作用”
notes=“方法的注意事项和备注”
@ApiModel()在实体类模块下使用，说明该实体类的作用
参数
description=“描述实体的作用”
@ApiModelProperty()在实体类的属性上使用，用于描述实体类的属性
参数
value=“用户名” 描述参数的意义
name=“name” 参数的变量名
required=true 参数是否必选
-
@ApiImplicitParams()controller 层的方法上多个参数的说明 -
@ApiImplicitParam()controller 层的方法上多个参数中每一个参数的说明
参数
name=“参数ming”
value=“参数说明”
dataType=“数据类型”
paramType=“query” 表示参数放在哪里
defaultValue=“参数的默认值”
required=“true” 表示参数是否必须传
@ApiParam()用于方法，参数，字段说明 表示对参数的要求和说明
参数
name=“参数名称”
value=“参数的简要说明”
defaultValue=“参数默认值”
required=“true” 表示属性是否必填，默认为false
@ApiResponses()用于请求的方法上，根据响应码表示不同响应
一个@ApiResponses包含多个@ApiResponse
@ApiResponse()用在请求的方法上，表示不同的响应
参数
code=“404” 表示响应码(int型)，可自定义
message=“状态码对应的响应信息”
-
@ApiIgnore()用于类或者方法上，不被显示在页面上 -
@Profile({"dev", "test"})用于配置类上，表示只对开发和测试环境有用
springboot 版本问题
出现问题是由于 springboot 的版本过高和 swagger 文档的不兼容
Error starting ApplicationContext. To display the conditions report re-run your application with 'debug' enabled.
2022-12-17 11:00:46.164 ERROR 8136 --- [ restartedMain] o.s.boot.SpringApplication : Application run failed
org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
<!--标志是springboot的项目-->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.7.2</version>
<relativePath/>
</parent>
降低版本
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.5.2</version>
<relativePath/>
</parent>
SQL 关键字异常
错误如下
2022-12-17 10:35:56.067 ERROR 10652 --- [p-nio-80-exec-5] o.a.c.c.C.[.[.[/].[dispatcherServlet] : Servlet.service() for servlet [dispatcherServlet] in context with path [] threw exception [Request processing failed; nested exception is org.springframework.jdbc.BadSqlGrammarException:
### Error updating database. Cause: java.sql.SQLSyntaxErrorException: You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'desc='12121'
where
id=1 and deleted=0' at line 7
### The error may exist in file [E:\Code\backproject\book\target\classes\mybatis\mapper\BookMapper.xml]
### The error may involve defaultParameterMap
### The error occurred while setting parameters
### SQL: update book set `name`=?, image=?, number=?, price=?, desc=? where id=? and deleted=0
### Cause: java.sql.SQLSyntaxErrorException: You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'desc='12121'
where
id=1 and deleted=0' at line 7
; bad SQL grammar []; nested exception is java.sql.SQLSyntaxErrorException: You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'desc='12121'
where
id=1 and deleted=0' at line 7] with root cause
java.sql.SQLSyntaxErrorException: You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'desc='12121'
where
id=1 and deleted=0' at line 7
原因数据库的字段是MySQL的关键字，这时候就需要加上（倒引号``）
<!-- SQL中的字段和关键字同名要使用 `desc` -->
<update id="update">
update book
set
`name`=#{name},
image=#{image},
number=#{number},
price=#{price},
`desc`=#{desc}
where
id=#{id} and deleted=0
</update>
SQL 的关键字
https://www.cnblogs.com/langtianya/p/4968132.html
Apifox 的使用
下载安装Apifox，https://www.apifox.cn/
使用导入数据
Apifox帮助文档
连接填写的是数据文档的Url
swagger2文档注释的文档数据地址
http://localhost/v2/api-docs
swagger3文档注释的文档数据地址
http://localhost/v3/api-docs
集中版本管理
采用集中的版本信息管理，方便版本信息的统一更新
<!-- 集中控制版本 编码 -->
<properties>
<junit.version>4.12</junit.version>
<lombok.version>1.18.12</lombok.version>
<log4j.version>1.2.17</log4j.version>
<druid.version>1.2.5</druid.version>
<jdbc.version>8.0.25</jdbc.version>
<maven.compiler.source>11</maven.compiler.source>
<maven.compiler.target>11</maven.compiler.target>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
版本控制所对应的依赖项目
<!-- junit 单元测试 -->
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>${junit.version}</version>
<scope>test</scope>
</dependency>
<!-- lombok 脚手架工具 -->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>${lombok.version}</version>
</dependency>
<!-- log4j日志信息 -->
<dependency>
<groupId>log4j</groupId>
<artifactId>log4j</artifactId>
<version>${log4j.version}</version>
</dependency>
<!-- alibaba的druid数据源 -->
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>druid-spring-boot-starter</artifactId>
<version>${druid.version}</version>
</dependency>
<!-- 数据库连接驱动器 -->
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<version>${jdbc.version}</version>
</dependency>
