基于Swagger+SpringBoot快速构建javaweb项目

章节导航

• SpringBoot&Swagger简介
• 数据模型和接口定义
• 项目框架生成
• 业务逻辑实现

项目源码地址
　　github项目路径：https://github.com/Vikezhu/springboot-template

一、SpringBoot&Swagger简介

　　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