基于Swagger+SpringBoot快速构建javaweb项目
章节导航
项目源码地址
github项目路径：https://github.com/Vikezhu/springboot-template
SpringBoot
SpringBoot实质上也是基于Spring的一种开发框架，但相比使用Spring框架那些复杂配置过程，以及集成其他框架时带来的诸多兼容性问题，SpringBoot可以更高效的搭建Spring框架，简化项目框架的配置，提升应用开发的效率，是开发人员更专注于应用的开发。而且SpringBoot还可以非常方便地集成各种主流框架（如SpringCloud、MyBatis等）。
目前，使用idea等IDE工具自带插件，或者通过 https://start.spring.io/ 网站，均可快速的构建一个空白的SpringBoot项目。
Swagger
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。它可以通过在线编辑接口文档和数据模型定义，快速生成SpringBoot项目，并构建出用户定义的对外服务restful接口，以及相关的数据实体类。另外，swagger生成的项目还内嵌由swagger-ui页面，方便开发和运维人员进行开发与故障定位。
Swagger是一组开源项目，包括的项目和工具有很多，这里只摘出本教程需要用的几个项目进行简要的介绍。
1、swagger-editor
swagger-editor是swagger项目提供的一个swagger文档编辑工具，使用浏览器打开即可快速编辑文档。（下载地址：https://github.com/swagger-api/swagger-editor，下载后解压压缩包，入口为文件夹中的index.html) swagger-editor页面如下图所示：
文档可以使用YAML或JSON两种格式编写，左边为编辑区，右边即时显示编辑后生成的接口定义等内容。
2、swagger-codegen
swagger-codegen 是专为解析swagger说明文档，生成工程框架代码的专用工具。（下载地址：https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/，下载swagger-codegen-cli.jar的jar包即可。）swagger-codegen 生成工程代码依赖于swagger-codegen-cli的jar包、swagger-editor编写的swagger说明文档（json格式）和swagger配置文件，swagger配置文件也是一个json文件，其中定义了工程名、包目录、java版本等信息。
首先用swagger-editor定义我们项目的数据模型和接口文档。这里我们以实现一个简单的用户管理系统为目标，实现用户数据的增删改查功能。
打开swagger-editor的编辑界面，可以看到有一个PetStore的示例。整个说明文档由几类信息组成，这里选取重点信息进行解说说明：
1、基础信息
swagger: #swagger版本
info:
title: #标题
description: #文档说明
version: #文档版本
2、基本url
host： #主机地址
basePath： #url前缀
schemes: #网络请求协议：http/https
3、API标签
tags：
4、接口定义
paths：
/user:
post: #新增接口
tags: #所属标签
operationId: #方法名(生成代码后即是controller层的接口方法名)
produces: #生产格式：json/xml
consumes: #消费格式：json/xml
parameters: #请求参数定义
-name: #参数名
in: #参数类型：可选：body/query/path，分别代表：请求体/url拼接参数/url占位符替换
required： #是否必需：true/false
schema: #参数结构,可引用definitions中定义的数据模型
$ref:'#/definitions/User'
responses: #返回格式定义
get: #查询接口
delete: #删除接口
put: #修改接口
'/user/{userId}':
get: #查询详情接口
5、数据模型定义
definitions:
User: #用户User类
type: #类型:object
properties: #参数列表
userId: #用户ID
type: #参数类型:object/integer/string/array等
format: #参数格式：int32/date-time
items: #若是前序的type为array，则需要定义items中的数据类型
type:
description： #参数描述
更多说明，请参考swagger editor官方文档：https://swagger.io/specification/v2/
按照需求定义好接口及数据字典后，点击页面上方的菜单栏：File——Convert and save as JSON，将说明文档保存到本地。
将swagger-editor编辑好的说明文档导出为json文件后（swagger.json），移动至swagger-codegen-cli.jar所在的目录下，并在该目录下创建名为swagger_cfg.json的json配置文件，内容如下图所示：
{
"groupId":"vike.server",
"artifactId":"ums",
"modelPackage":"com.vike.server.ums.model",
"apiPackage":"com.vike.server.ums.api",
"basePackage":"com.vike.server.ums",
"configPackage":"com.vike.server.ums.config",
"java8":"true"
}
其中groupId和artifactId为项目对应的组织名和模块名。
之后，打开cmd.exe，进入到swagger-codegen-cli.jar所在的目录后，执行以下命令，自动生成工程：
java -jar swagger-codegen-cli.jar generate -l spring -c swagger_cfg.json -i swagger.json -o D:\Code\ums
其中,-c后的参数为配置文件，-i后的参数为swagger说明文档，-o为生成工程代码的导出路径。
根据swagger-codegen的版本不同，工程中maven依赖的SpringBoot版本可能有所不同，大家可以根据自己的需求修改相关的版本依赖。本项目采用了spring-boot-starter-parent的2.0.4.RELEASE版本。（PS：这里在使用2.X版本的springboot时有个坑，工程中的配置文件application.properties中，server.contextPath参数已弃用，应该改为server.servlet.context-path才能正确运行。）
工程的入口类为basePackage下的Swagger2SpringBoot.java，运行该类，当控制台打印诸如：Started Swagger2SpringBoot in 7.032 seconds (JVM running for 8.761)的内容时，说明应用启动成功。打开浏览器，输入地址： http://localhost:8080/ums/api/v1/swagger-ui.html （默认端口为8080），若显示如下页面，说明应用启动成功。
后续的接口联调及上线后的运维均可通过此页面来进行，界面简洁，十分方便。至此，工程代码框架即已搭建完成。
1、数据库准备
我们在ums库下创建一张ums_user的表，sql创表语句如下：
CREATE TABLE `ums_user` ( `user_id` varchar(100) NOT NULL, `username` varchar(100) NOT NULL, `age` int(11) NOT NULL, `code` varchar(100) NOT NULL, `phone` varchar(100) NOT NULL, `apartment` varchar(100) NOT NULL, `biz_line` varchar(100) NOT NULL, `email` varchar(100) NOT NULL, `entry_time` varchar(100) NOT NULL, `status` int(11) NOT NULL ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
成功创表后，在表中随意插入两条数据。
2、依赖引入及配置信息
mybatis和mysql依赖的引入：
<!--Spring Boot Mybatis 依赖--> <dependency> <groupId>org.mybatis.spring.boot</groupId> <artifactId>mybatis-spring-boot-starter</artifactId> <version>${mybatis-spring-boot}</version> </dependency> <!--MySQL 连接驱动依赖--> <dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <version>${mysql-connector}</version> </dependency>
mysql数据库连接配置信息：
# mybatis
#mybatis xml文件所在路径 mybatis.mapperLocations = classpath:/mapper/*.xml
#实体类包路径 mybatis.typeAliasesPackage = com.vike.server.ums.model # mysql spring.datasource.url=jdbc:mysql://localhost:3306/ums？useUnicode=true&characterEncoding=utf8&useSSL=false spring.datasource.username=root spring.datasource.password=root spring.datasource.driver-class-name=com.mysql.jdbc.Driver
3、实现用户的增删改查
*.api包下为Controller层：实现UserApiController类继承的接口的增删改查方法。
创建*.service包，新建UserService接口，定义增删改查方法。
创建*.service.impl包，新建UserServiceImpl方法，实现UserService接口及其方法。将UserServiceImpl类添加@Service注解。
创建*.dao包，新建UserDao接口，定义增删改查方法。
在resources目录下，新建名为mapper的文件夹，创建名为UserMapper.xml的文件。注意mapper的命名空间namespace的值必须指向UserDao的全路径。
启动类Swagger2SpringBoot中添加注解@MapperScan("com.vike.server.ums.dao")，扫描mapper接口类。
4、启动Swagger2SpringBoot，打开swagger-ui页面，即可进行接口的验证和调试！
项目源码请参考文章开始处的链接！！如有任何疑问和建议，欢迎沟通交流。
参考文献：（文章仅做交流学习，侵权即删！！）
