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

你说的曾经没有我的故事 提交于 2021-01-20 07:34:48

章节导航

项目源码地址
  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

易学教程内所有资源均来自网络或用户发布的内容,如有违反法律规定的内容欢迎反馈
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!