章节导航
项目源码地址
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页面,即可进行接口的验证和调试!
项目源码请参考文章开始处的链接!!如有任何疑问和建议,欢迎沟通交流。
参考文献:(文章仅做交流学习,侵权即删!!)
1、https://www.bysocket.com/technique/1610.html
来源:oschina
链接:https://my.oschina.net/u/4277063/blog/3497912