基於Swagger+SpringBoot快速構建javaweb項目

章節導航

• SpringBoot&Swagger簡介
• 數據模型和接口定義
• 項目框架生成
• 業務邏輯實現

項目源碼地址
　　github項目路徑：https://github.com/Vikezhu/springboot-template

 

1、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是一組開源項目，包括的項目和工具備不少，這裏只摘出本教程須要用的幾個項目進行簡要的介紹。

　　一、swagger-editor

　　swagger-editor是swagger項目提供的一個swagger文檔編輯工具，使用瀏覽器打開便可快速編輯文檔。（下載地址：https://github.com/swagger-api/swagger-editor，下載後解壓壓縮包，入口爲文件夾中的index.html) swagger-editor頁面以下圖所示：

　　

　　文檔可使用YAML或JSON兩種格式編寫，左邊爲編輯區，右邊即時顯示編輯後生成的接口定義等內容。

　　二、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版本等信息。

 

2、數據模型和接口定義

　　首先用swagger-editor定義咱們項目的數據模型和接口文檔。這裏咱們以實現一個簡單的用戶管理系統爲目標，實現用戶數據的增刪改查功能。　

　　打開swagger-editor的編輯界面，能夠看到有一個PetStore的示例。整個說明文檔由幾類信息組成，這裏選取重點信息進行解說說明：

　　一、基礎信息
　　　　swagger: 　　 #swagger版本
　　　　info:
　　　　　　title: 　　 #標題
　　　　　　description: 　　#文檔說明
　　　　　　version: 　　　 #文檔版本
　　二、基本url
　　　　host： 　　　　 #主機地址
　　　　basePath： 　　 #url前綴
　　　　schemes: 　　#網絡請求協議：http/https
　　三、API標籤
　　　　tags：
　　四、接口定義
　　　　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:　　　　#查詢詳情接口
　　五、數據模型定義
　　　　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，將說明文檔保存到本地。

3、項目框架生成

　　將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），若顯示以下頁面，說明應用啓動成功。

　　

　　後續的接口聯調及上線後的運維都可經過此頁面來進行，界面簡潔，十分方便。至此，工程代碼框架即已搭建完成。 

4、業務邏輯實現

　　一、數據庫準備

　　咱們在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;

　　成功創表後，在表中隨意插入兩條數據。

　　二、依賴引入及配置信息

　　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 

　　三、實現用戶的增刪改查

　　*.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接口類。

　　四、啓動Swagger2SpringBoot，打開swagger-ui頁面，便可進行接口的驗證和調試！

　　項目源碼請參考文章開始處的連接！！若有任何疑問和建議，歡迎溝通交流。

 

參考文獻：（文章僅作交流學習，侵權即刪！！）

一、https://www.bysocket.com/technique/1610.html