寫在前面
距離上一次分享整合SpringBoot過去了大半年了，時(shí)光荏苒捧杉，今天將繼續(xù)更新SpringBoot的相關(guān)技術(shù)點(diǎn)。
Swagger
這里品山，我就不過多介紹Swagger是什么了述雾，相信你看這文章的時(shí)候也是有了解Swagger的相關(guān)概念的吼鱼。簡(jiǎn)單的說，Swagger就是一種定義接口信息的規(guī)范绰咽。具體可以參見Swagger官網(wǎng)（https://swagger.io）
SpringBoot整合Swagger
下面分享一下SpringBoot整合Swagger的內(nèi)容菇肃，看一下如何在一個(gè)既有的SpringBoot工程下整合Swagger。
SpringBoot初始工程
啟動(dòng)類 SpringbootSwaggerApplication.java
package top.flygrk.ishare.springbootswagger;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class SpringbootSwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(SpringbootSwaggerApplication.class, args);
}
}
實(shí)體類 User.java
注意：這里采用lombok插件及注解
package top.flygrk.ishare.springbootswagger.entity;
import lombok.Data;
/**
* @Package top.flygrk.ishare.springbootswagger.entity
* @Author wuzy
* @Date 2019/8/5 11:05
* @Version V1.0
* @Description:
*/
@Data
public class User {
private String id;
private String username;
private int age;
private String note;
}
接口類 UserController.java
我們這里有2個(gè)api接口：插入用戶insert和根據(jù)用戶id查詢用戶信息取募。這里均采用模擬的方式琐谤，無service及dao層的處理邏輯。
package top.flygrk.ishare.springbootswagger.controller;
import com.alibaba.fastjson.JSONObject;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import top.flygrk.ishare.springbootswagger.entity.User;
/**
* @Package top.flygrk.ishare.springbootswagger.controller
* @Author wuzy
* @Date 2019/8/5 11:07
* @Version V1.0
* @Description: 用戶接口
*/
@RestController
@RequestMapping("user")
public class UserController {
/**
* @Authod wuzy
* @Date 2019/8/5 11:09
* @Method insert
* @Param user
* @ReturnType Object
* @Description: 插入用戶信息
*/
@RequestMapping(value = "insert", method = RequestMethod.POST)
public Object insert(@RequestBody User user) {
JSONObject jsonObject = new JSONObject();
if (user == null) {
jsonObject.put("result", "failed");
jsonObject.put("reason", "user is null");
return jsonObject;
}
jsonObject.put("result", "success");
jsonObject.put("msg", user.getUsername());
return jsonObject;
}
@RequestMapping(value = "findById", method = RequestMethod.GET)
public Object findById(String id) {
JSONObject jsonObject = new JSONObject();
if (StringUtils.isEmpty(id)) {
jsonObject.put("result", "failed");
jsonObject.put("reason", "user is null");
return jsonObject;
}
jsonObject.put("id", id);
jsonObject.put("username", "wuzy");
jsonObject.put("age", 20);
jsonObject.put("note", "coding boy");
return jsonObject;
}
}
Swagger簡(jiǎn)單使用
我們先來看下如何初步使用Swagger玩敏，最方便的一種斗忌。首先添加maven依賴，然后再引入Swagger的注解即可旺聚。我們來仔細(xì)看看：
引入pom依賴
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.9.0.RELEASE</version>
</dependency>
添加Swagger注解
我們只需要在啟動(dòng)類SpringbootSwaggerApplication添加注解@EnableSwagger2Doc织阳，即可完成對(duì)Swagger的簡(jiǎn)單整合，是不是so easy!!!
@SpringBootApplication
@EnableSwagger2Doc
public class SpringbootSwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(SpringbootSwaggerApplication.class, args);
}
}
驗(yàn)證
我們啟動(dòng)程序砰粹，去驗(yàn)證一下是否可以使用Swagger唧躲。我們通過訪問http://127.0.0.1:9000/swagger-ui.html，可以看到如下界面：
我們?cè)僬归_看下user-controller下的內(nèi)容：
從上圖可以看出碱璃，再user-controller下弄痹，存在兩個(gè)接口，分別為/user/findById 和 /user/insert嵌器。同時(shí)也可以看出其訪問方式為GET/POST信息肛真。我們以 /user/findById為例，來看下其具體內(nèi)容：
我們可以看到其需要的請(qǐng)求參數(shù)為id爽航，類型為String等信息蚓让。并且我們可以使用后面的【Try it out】按鈕，調(diào)用findById接口讥珍。我們來調(diào)用一下試試：
Swagger補(bǔ)充
有沒有覺得上面簡(jiǎn)單的那個(gè)Swagger-UI很難閱讀历极？那么下面，我們繼續(xù)來優(yōu)化下他的提示信息串述，我們通過相關(guān)注解來具體的描述接口的相關(guān)信息执解，比如類的含義、接口的含義纲酗、參數(shù)的含義等信息衰腌，具體代碼如下：
UserController.java
package top.flygrk.ishare.springbootswagger.controller;
import com.alibaba.fastjson.JSONObject;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import top.flygrk.ishare.springbootswagger.entity.User;
/**
* @Package top.flygrk.ishare.springbootswagger.controller
* @Author wuzy
* @Date 2019/8/5 11:07
* @Version V1.0
* @Description: 用戶接口
*/
@RestController
@RequestMapping("user")
@Api("用戶管理模塊")
public class UserController {
/**
* @Authod wuzy
* @Date 2019/8/5 11:09
* @Method insert
* @Param user
* @ReturnType Object
* @Description: 插入用戶信息
*/
@RequestMapping(value = "insert", method = RequestMethod.POST)
@ApiOperation(value = "插入用戶信息", notes = "插入用戶的詳細(xì)信息")
public Object insert(@RequestBody User user) {
JSONObject jsonObject = new JSONObject();
if (user == null) {
jsonObject.put("result", "failed");
jsonObject.put("reason", "user is null");
return jsonObject;
}
jsonObject.put("result", "success");
jsonObject.put("msg", user.getUsername());
return jsonObject;
}
@RequestMapping(value = "findById", method = RequestMethod.GET)
@ApiOperation(value = "查詢用戶信息", notes = "根據(jù)id查詢用戶信息")
public Object findById(@ApiParam(value = "用戶id", required = true) String id) {
JSONObject jsonObject = new JSONObject();
if (StringUtils.isEmpty(id)) {
jsonObject.put("result", "failed");
jsonObject.put("reason", "user is null");
return jsonObject;
}
jsonObject.put("id", id);
jsonObject.put("username", "wuzy");
jsonObject.put("age", 20);
jsonObject.put("note", "coding boy");
return jsonObject;
}
}
User.java
package top.flygrk.ishare.springbootswagger.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
/**
* @Package top.flygrk.ishare.springbootswagger.entity
* @Author wuzy
* @Date 2019/8/5 11:05
* @Version V1.0
* @Description:
*/
@Data
@ApiModel
public class User {
@ApiModelProperty(value = "用戶id", required = true, dataType = "String")
private String id;
@ApiModelProperty(value = "用戶名", dataType = "String")
private String username;
@ApiModelProperty(value = "年紀(jì)", dataType = "int")
private int age;
@ApiModelProperty(value = "備注", dataType = "String")
private String note;
}
進(jìn)行上述修改之后，我們?cè)俅螁?dòng)SpringBoot工程右蕊，打開Swagger-UI，可以看到內(nèi)容如下：
首先吮螺，展開看一下“查詢用戶信息接口”饶囚，可以看出在id后面的Description下有“用戶id”的提示信息：
然后，我們來仔細(xì)看看insert接口的信息:
關(guān)于注解的說明本文暫時(shí)不再敘述鸠补，請(qǐng)大家參閱其他資料萝风。整合Swagger的入門篇就說到這，還有一些其他的注解紫岩，以后再進(jìn)行分享规惰。例如:
