Springboot+Maven+Mybatis+SwaggerUI的搭建详细说明

本文章详细记录如何从零搭建Springboot+Maven+Mybatis+SwaggerUI的JavaWeb。

  Springboot究竟是什么网上有特别多的说明，因此这里不再阐述。网上实操搭建例子虽然也很多，但各个稍微有差异，本文只根据本人使用风格直接记录实操的代码搭建。
  使用工具及环境为IDEA，JDK1.8以上，Maven。

一、创建Springboot项目

使用spring initializr创建项目。

点击下一步，配置项目包名，类型Type记得选择Maven，不然默认的可能是grandle。
有的idea版本在Type中可能有两个版本，记得选Maven (generate a maven based project archive.),而不要选Maven POM,否则项目生成后识别不到src。

点击下一步，这里只创建最基本的web，所以只选择了spring web服务，有需要的可以另外进行选择。

最后定好项目命名，路径这里注意，一定是选择提前为单个项目创建好的项目文件夹

二、pom配置文件

涉及到使用什么包均在代码注释。

1.jar包形式。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.xizi</groupId>
    <artifactId>Demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>Demo</name>
    <description>Demo project for Spring Boot</description>

    <repositories>
        <!-- 阿里云 maven 镜像云 -->
        <repository>
            <id>alimaven</id>
            <name>aliyun maven</name>
            <url>https://maven.aliyun.com/repository/public/</url>
        </repository>
        <!--中国开源社区 -->
        <repository>
            <id>oschina-repos</id>
            <name>Oschina Releases</name>
            <url>http://maven.oschina.net/content/groups/public</url>
        </repository>
    </repositories>


    <properties>
        <java.version>1.8</java.version>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <spring-boot.version>2.3.7.RELEASE</spring-boot.version>
        <log4j.version>1.2.17</log4j.version>
    </properties>

    <dependencies>
    	<!-- springboot启动包 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <!-- springboot mybatis核心包 -->
        <dependency>
            <groupId>org.mybatis.spring.boot</groupId>
            <artifactId>mybatis-spring-boot-starter</artifactId>
            <version>1.3.2</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-thymeleaf</artifactId>
        </dependency>

        <!-- 导入oracle包 -->
        <dependency>
            <groupId>com.oracle</groupId>
            <artifactId>ojdbc8</artifactId>
            <version>12.2.0.1</version>
        </dependency>
        <!-- 导入mysql包 -->
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <version>8.0.30</version>
        </dependency>

        <!-- 导入java ee jar 包 -->
        <dependency>
            <groupId>javax</groupId>
            <artifactId>javaee-api</artifactId>
            <version>7.0</version>
        </dependency>

        <!-- druid监控依赖 -->
        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>druid-spring-boot-starter</artifactId>
            <version>1.1.9</version>
        </dependency>

        <!-- log start -->
        <dependency>
            <groupId>log4j</groupId>
            <artifactId>log4j</artifactId>
            <version>${log4j.version}</version>
        </dependency>
        <!-- 格式化对象，方便输出日志 -->
        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>fastjson</artifactId>
            <version>1.2.83</version>
        </dependency>

		<!-- swagger -->
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!--        美化增强swaggerUI-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-ui</artifactId>
            <version>3.0.3</version>
        </dependency>
    </dependencies>


    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-dependencies</artifactId>
                <version>${spring-boot.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                    <encoding>UTF-8</encoding>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>2.3.7.RELEASE</version>
                <configuration>
                    <mainClass>com.xizi.demo.DemoApplication</mainClass>
                </configuration>
                <executions>
                    <execution>
                        <id>repackage</id>
                        <goals>
                            <goal>repackage</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

</project>

2.war包形式

若希望打包成war包的形式，则在以上的pom配置基础上，做出修改：

（1）补充两个依赖包

		<dependency>
			<groupId>javax.servlet</groupId>
			<artifactId>javax.servlet-api</artifactId>
			<version>3.1.0</version>
			<scope>provided</scope>
		</dependency>

		<dependency>
		    <groupId>jakarta.xml.bind</groupId>
		    <artifactId>jakarta.xml.bind-api</artifactId>
		    <version>2.3.3</version>
		</dependency>

（2）修改springboot启动包配置，加上exclusions标签

		<dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
            <exclusions>
		        <exclusion>
		            <groupId>org.springframework.boot</groupId>
		            <artifactId>spring-boot-starter-tomcat</artifactId>
		        </exclusion>
		    </exclusions>
        </dependency>

（3）在pom文件，project标签内添加一个packaging标签

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    
    	//......
    	
		<packaging>war</packaging>

</project>

完成以上三点修改即可打包成war。

三、创建完善项目目录结构

config包用于存放SwaggerUI相关配置文件，springboot的配置我们改为采用yml形式的配置文件进行配置。

四、application-xx.yml配置

  application-xx.yml可用于不同版本环境进行自定义配置，xx为定义的命名参数。
  这里演示的demo分为生产环境与测试环境，二者的区别只在于数据库，因此这里的两份配置文件只配数据库相关配置。
  测试环境命名test，则为application-test.yml；正式环境命名dev，则为application-dev.yml。

数据库的不同主要区别为数据库驱动包引用的不同。

1.采用oracle则配置方式如下

spring:
  datasource:
        url: jdbc:oracle:thin:@localhost:1521/orcl
        driver-class-name: oracle.jdbc.OracleDriver
        username: demo
        password: 123456

2.如果用的是mysql，可如下配置

spring:
        datasource:
                url: jdbc:mysql://localhost:3306/Demo?useSSL=false&useUnicode=true&characterEncoding=utf-8
                driver-class-name: com.mysql.cj.jdbc.Driver
                username: demo
                password: 123456

五、application.yml配置

  springboot的配置主要以application.yml为主，优先找application.yml的配置，其次再对应spring.profiles.active对应的参数配置找相关文件配置。

这里注意，如果选择jar包形式，yml配置的端口号才生效。war包形式则对应tomcat的端口生效。

server:
  port: 8089
  servlet:
    context-path: /Demo

spring:
  thymeleaf:
    prefix: classpath:templates/
  profiles:
    active: test  # 这个参数是用于指定我们上一步配置的文件是采用 
    			  # 哪份application-xx.yml，对应写入xx

mybatis:
  mapper-locations: classpath:mapper/*.xml
  type-aliases-package: com.xizi.demo.entity
  configuration:
    map-underscore-to-camel-case: true  #开启驼峰功能
    cache-enabled: false

六、log文件log4j.properties配置

log4j.rootCategory=INFO, stdout , R
   
log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%d %p [%t] %C.%M(%L) | %m%n
log4j.appender.stdout.Encoding=UTF-8
    
log4j.appender.R=org.apache.log4j.DailyRollingFileAppender
log4j.appender.R.File=E://logs//Demo.log #日志文件路径
log4j.appender.R.layout=org.apache.log4j.PatternLayout
log4j.appender.R.layout.ConversionPattern=%d-[TS] %p %t %c - %m%n
log4j.appender.R.Encoding=UTF-8

log4j.logger.org.hibernate.ps.PreparedStatementCache=INFO
log4j.logger.org.hibernate=INFO

log4j.category.org.hibernate.SQL=INFO
log4j.category.org.hibernate.type=INFO

log4j.logger.org.hibernate.type.descriptor.sql.BasicBinder=INFO
log4j.loggerorg.hibernate.type.descriptor.sql.BasicExtractor=INFO

#-----------------------------------#
#3 druid
log4j.logger.druid.sql=INFO
log4j.logger.druid.sql.DataSource=INFO
log4j.logger.druid.sql.Connection=INFO
log4j.logger.druid.sql.Statement=INFO
log4j.logger.druid.sql.ResultSet=INFO

#4 mybatis 显示SQL语句部分
log4j.logger.org.mybatis=INFO
log4j.logger.java.sql=INFO
log4j.logger.java.sql.Statement=INFO
log4j.logger.java.sql.ResultSet=INFO
log4j.logger.java.sql.PreparedStatement=INFO

七、SwaggerUI配置

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Demo 1.0 项目接口文档")
                .description("Demo 1.0 项目接口文档")
                .version("1.0.0")
                .termsOfServiceUrl("")
                .license("")
                .licenseUrl("")
                .build();
    }
    
}

到这里其实我们已经可以正常启动项目了。

  如果一开始选择的是jar包形式，启动的时候只需要选择自带的启动类程序，从main函数进入执行，端口号依据yml配置的端口来。
 
  如果选择的是war包形式，那么跟spring启动的方式一样，自行添加tomcat启动。

要想项目可以实现接口调用还需要补充一些配置。

八、代码编写

1.重新编写启动类

@MapperScan注解在启动类中不可缺少，参数为mapper对应定义接口的包，是用于mybatis扫描包的时候找到对应的实现类接口。

@SpringBootApplication
@MapperScan("com.xizi.demo.dao")
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }

}

2.Dao层的配置

@Repository注解需要放在dao接口层，与启动类中的@MapperScan()注解相对应搭配使用，标识是该接口需要被扫描。

@Repository
public interface TestDao {
    List<Test> select();
}

3.Mapper的编写

创建TestDao对应的mapper文件。

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd" >
<mapper namespace="com.xizi.demo.dao.TestDao">

    <select id="select" resultType="com.xizi.demo.entity.Test">
            select * from test
    </select>

</mapper>

4.service层编写

@Service("TestService")
public class TestService {
    /**
     * 日志
     */
    private static Logger logger = Logger.getLogger(TestService.class);

    @Autowired
    TestDao testDao;

    public List<Test> select(){
        logger.info("---进入查询---");
        return testDao.select();
    }
}

5.controller层编写接口

@ApiOperation注解属于SwaggerUI的注解，用于文档标识接口作用，httpMethod参数尽量标明，否则前端文档识别不到属于什么类型的请求接口，会将所有类型请求枚举展示一遍。

@Controller
@RequestMapping("/test")
public class TestController {
    @Autowired
    TestService testService;

    @RequestMapping("/find")
    @ResponseBody 
    @ApiOperation(value = "查询接口", notes = "测试查询", httpMethod = "POST")
    public List<Test> find(HttpServletRequest request){

        return testService.select();
    }

}

九、测试成功

登录 http://localhost:8089/Demo/doc.html# 调用接口，可以看到数据正常返回。

---

同时也能看到日志正常生成。