SpringBoot使用Swagger2實現Restful API
很多時候，我們需要建立一個介面專案用來資料調轉，其中不包含任何業務邏輯，比如我們公司。這時我們就需要實現一個具有Restful API的介面專案。
本文介紹springboot使用swagger2實現Restful API。
本專案使用mysql+jpa+swagger2。
首先pom中加入swagger2，程式碼如下：
4.0.0 com.dalaoyang springboot_swagger2 0.0.1-SNAPSHOT jar springboot_swagger2 springboot_swagger2 org.springframework.boot spring-boot-starter-parent 1.5.9.RELEASE <!-- lookup parent from repository --> UTF-8 UTF-8 1.8 org.springframework.boot spring-boot-starter-data-jpa org.springframework.boot spring-boot-starter-web org.springframework.boot spring-boot-devtools runtime mysql mysql-connector-java runtime org.springframework.boot spring-boot-starter-test test io.springfox springfox-swagger2 2.2.2 io.springfox springfox-swagger-ui 2.2.2 org.springframework.boot spring-boot-maven-plugin
接下來是配置檔案，和整合jpa一樣。程式碼如下：
##埠號 server.port=8888 ##資料庫配置 ##資料庫地址 spring.datasource.url=jdbc:mysql://localhost:3306/test?characterEncoding=utf8&useSSL=false ##資料庫使用者名稱 spring.datasource.username=root ##資料庫密碼 spring.datasource.password=root ##資料庫驅動 spring.datasource.driver-class-name=com.mysql.jdbc.Driver
建立一個swagger2配置類，簡單解釋一下，@Configuration註解讓spring來載入配置，@EnableSwagger2開啟swagger2。
package com.dalaoyang.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @author dalaoyang
* @Description
* @project springboot_learn
* @package com.dalaoyang.config
* @email yangyang@dalaoyang.cn
* @date 2018/4/9
*/
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.dalaoyang.swagger"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("使用Swagger2構建RESTful APIs")
.description("關注博主部落格：")
.termsOfServiceUrl("")
.contact("dalaoyang")
.version("1.0")
.build();
}
}
建立一個user類作為model
package com.dalaoyang.model;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.Id;
import javax.validation.constraints.NotNull;
/**
* @author dalaoyang
* @Description
* @project springboot_learn
* @package com.dalaoyang.model
* @email yangyang@dalaoyang.cn
* @date 2018/4/9
*/
@Entity
@ApiModel(description = "user")
public class User {
@ApiModelProperty(value = "主鍵id",hidden = true)
@GeneratedValue
@Id
int id;
@ApiModelProperty(value = "使用者名稱稱")
@NotNull
@Column
String userName;
@ApiModelProperty(value = "使用者密碼")
@Column
String userPassword;
public int getId() {
return id;
}
public void setId(int id) {
this.id = id;
}
public String getUserName() {
return userName;
}
public void setUserName(String userName) {
this.userName = userName;
}
public String getUserPassword() {
return userPassword;
}
public void setUserPassword(String userPassword) {
this.userPassword = userPassword;
}
public User(int id, String userName, String userPassword) {
this.id=id;
this.userName = userName;
this.userPassword = userPassword;
}
public User(String userName, String userPassword) {
this.userName = userName;
this.userPassword = userPassword;
}
public User() {
}
}
jpa資料操作類UserRepository
package com.dalaoyang.repository; import com.dalaoyang.model.User; import org.springframework.data.jpa.repository.JpaRepository; /** * @author dalaoyang * @Description * @project springboot_learn * @package com.dalaoyang.repository * @email yangyang@dalaoyang.cn * @date 2018/4/9 */ public interface UserRepository extends JpaRepository{ User findById(int id); }
然後新增文件內容，其實和寫controller一樣，只不過方法和引數中間穿插一些註解。
package com.dalaoyang.swagger;
import com.dalaoyang.model.User;
import com.dalaoyang.repository.UserRepository;
import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import java.util.List;
/**
* @author dalaoyang
* @Description
* @project springboot_learn
* @package com.dalaoyang.swagger
* @email yangyang@dalaoyang.cn
* @date 2018/4/9
*/
@RestController
@RequestMapping(value="/users")
@Api(value="使用者操作介面",tags={"使用者操作介面"})
public class UserSwagger {
@Autowired
UserRepository userRepository;
@ApiOperation(value="獲取使用者詳細資訊", notes="根據使用者的id來獲取使用者詳細資訊")
@ApiImplicitParam(name = "id", value = "使用者ID", required = true,paramType = "query", dataType = "Integer")
@GetMapping(value="/findById")
public User findById(@RequestParam(value = "id")int id){
User user = userRepository.findById(id);
return user;
}
@ApiOperation(value="獲取使用者列表", notes="獲取使用者列表")
@GetMapping(value="/getUserList")
public List getUserList(){
return userRepository.findAll();
}
@ApiOperation(value="儲存使用者", notes="儲存使用者")
@PostMapping(value="/saveUser")
public String saveUser(@RequestBody @ApiParam(name="使用者物件",value="傳入json格式",required=true) User user){
userRepository.save(user);
return "success!";
}
@ApiOperation(value="修改使用者", notes="修改使用者")
@ApiImplicitParams({
@ApiImplicitParam(name="id",value="主鍵id",required=true,paramType="query",dataType="Integer"),
@ApiImplicitParam(name="username",value="使用者名稱稱",required=true,paramType="query",dataType = "String"),
@ApiImplicitParam(name="password",value="使用者密碼",required=true,paramType="query",dataType = "String")
})
@GetMapping(value="/updateUser")
public String updateUser(@RequestParam(value = "id")int id,@RequestParam(value = "username")String username,
@RequestParam(value = "password")String password){
User user = new User(id, username, password);
userRepository.save(user);
return "success!";
}
@ApiOperation(value="刪除使用者", notes="根據使用者的id來刪除使用者")
@ApiImplicitParam(name = "id", value = "使用者ID", required = true,paramType = "query", dataType = "Integer")
@DeleteMapping(value="/deleteUserById")
public String deleteUserById(@RequestParam(value = "id")int id){
User user = userRepository.findById(id);
userRepository.delete(user);
return "success!";
}
}
啟動專案，訪問，可以看到如下圖
為了方便大家學習觀看，我分別用了幾種不同的方法寫，
1.刪除使用者，程式碼如下
@ApiOperation(value="刪除使用者", notes="根據使用者的id來刪除使用者")
@ApiImplicitParam(name = "id", value = "使用者ID", required = true,paramType = "query", dataType = "Integer")
@DeleteMapping(value="/deleteUserById")
public String deleteUserById(@RequestParam(value = "id")int id){
User user = userRepository.findById(id);
userRepository.delete(user);
return "success!";
}
2.獲取使用者詳細資訊
@ApiOperation(value="獲取使用者詳細資訊", notes="根據使用者的id來獲取使用者詳細資訊")
@ApiImplicitParam(name = "id", value = "使用者ID", required = true,paramType = "query", dataType = "Integer")
@GetMapping(value="/findById")
public User findById(@RequestParam(value = "id")int id){
User user = userRepository.findById(id);
return user;
}
3.獲取使用者列表
@ApiOperation(value="獲取使用者列表", notes="獲取使用者列表")
@GetMapping(value="/getUserList")
public List getUserList(){
return userRepository.findAll();
}
4.儲存使用者
@ApiOperation(value="儲存使用者", notes="儲存使用者")
@PostMapping(value="/saveUser")
public String saveUser(@RequestBody @ApiParam(name="使用者物件",value="傳入json格式",required=true) User user){
userRepository.save(user);
return "success!";
}
5.修改使用者
@ApiOperation(value="修改使用者", notes="修改使用者")
@ApiImplicitParams({
@ApiImplicitParam(name="id",value="主鍵id",required=true,paramType="query",dataType="Integer"),
@ApiImplicitParam(name="username",value="使用者名稱稱",required=true,paramType="query",dataType = "String"),
@ApiImplicitParam(name="password",value="使用者密碼",required=true,paramType="query",dataType = "String")
})
@PutMapping(value="/updateUser")
public String updateUser(@RequestParam(value = "id")int id,@RequestParam(value = "username")String username,
@RequestParam(value = "password")String password){
User user = new User(id, username, password);
userRepository.save(user);
return "success!";
}
然後給大家分享一下我之前學習時記錄在有道雲筆記的關於swagger2的使用說明，原創作者是誰，我也記不清了。如果原創作者看到的話，可以私聊我，我給您的名字加上，抱歉。
@Api：用在請求的類上，表示對類的說明
tags="說明該類的作用，可以在UI介面上看到的註解"
value="該引數沒什麼意義，在UI介面上也看到，所以不需要配置"
示例：
@Api(tags="APP使用者註冊Controller")
@ApiOperation：用在請求的方法上，說明方法的用途、作用
value="說明方法的用途、作用"
notes="方法的備註說明"
示例：
@ApiOperation(value="使用者註冊",notes="手機號、密碼都是必輸項，年齡隨邊填，但必須是數字")
@ApiImplicitParams：用在請求的方法上，表示一組引數說明
@ApiImplicitParam：用在@ApiImplicitParams註解中，指定一個請求引數的各個方面
name：引數名
value：引數的漢字說明、解釋
required：引數是否必須傳
paramType：引數放在哪個地方
· header --> 請求引數的獲取：@RequestHeader
· query --> 請求引數的獲取：@RequestParam
· path（用於restful介面）--> 請求引數的獲取：@PathVariable
· body（不常用）
· form（不常用）
dataType：引數型別，預設String，其它值dataType="Integer"
defaultValue：引數的預設值
示例：
@ApiImplicitParams({
@ApiImplicitParam(name="mobile",value="手機號",required=true,paramType="form"),
@ApiImplicitParam(name="password",value="密碼",required=true,paramType="form"),
@ApiImplicitParam(name="age",value="年齡",required=true,paramType="form",dataType="Integer")
})
@ApiResponses：用在請求的方法上，表示一組響應
@ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應資訊
code：數字，例如400
message：資訊，例如"請求引數沒填好"
response：丟擲異常的類
@ApiOperation(value = "select1請求",notes = "多個引數，多種的查詢引數型別")
@ApiResponses({
@ApiResponse(code=400,message="請求引數沒填好"),
@ApiResponse(code=404,message="請求路徑沒有或頁面跳轉路徑不對")
})
@ApiModel：用於響應類上，表示一個返回響應資料的資訊
（這種一般用在post建立的時候，使用@RequestBody這樣的場景，
請求引數無法使用@ApiImplicitParam註解進行描述的時候）
@ApiModelProperty：用在屬性上，描述響應類的屬性
示例：
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.io.Serializable;
@ApiModel(description= "返回響應資料")
public class RestMessage implements Serializable{
@ApiModelProperty(value = "是否成功")
private boolean success=true;
@ApiModelProperty(value = "返回物件")
private Object data;
@ApiModelProperty(value = "錯誤編號")
private Integer errCode;
@ApiModelProperty(value = "錯誤資訊")
private String message;
}
POST請求傳入物件
示例：
@ApiOperation(value="儲存使用者", notes="儲存使用者")
@RequestMapping(value="/saveUser", method= RequestMethod.POST)
public String saveUser(@RequestBody @ApiParam(name="使用者物件",value="傳入json格式",required=true) User user){
userDao.save(user);
return "success!";
}
來自 “ ITPUB部落格 ” ，連結：http://blog.itpub.net/855/viewspace-2810757/，如需轉載，請註明出處，否則將追究法律責任。
相關文章
- 企業級SpringBoot教程（十一）springboot整合swagger2，構建Restful APISpring BootSwaggerRESTAPI
- SpringBoot 實戰 (四) | 整合 Swagger2 構建強大的 RESTful API 文件Spring BootSwaggerRESTAPI
- SpringBoot Restful 介面實現Spring BootREST
- nodejs實現restful APINodeJSRESTAPI
- DRF使用超連結API實現真正RESTfulAPIREST
- SpringBoot整合Redis使用Restful風格實現CRUD功能Spring BootRedisREST
- SpringBoot整合Swagger2及使用Spring BootSwagger
- SpringBoot整合Redis開發RESTful API介面Spring BootRedisRESTAPI
- 實現一個簡單的 RESTful APIRESTAPI
- 使用JWT做RESTful API的身份驗證-Go語言實現JWTRESTAPIGo
- 如何使用Node.js、TypeScript和Express實現RESTful API服務Node.jsTypeScriptExpressRESTAPI
- 微服務雲架構-Swagger2構建強大的RESTful API文件微服務架構SwaggerRESTAPI
- RESTful API 最佳實踐RESTAPI
- restful api最佳實踐RESTAPI
- Spring Boot中使用Swagger2構建RESTful APIs介紹Spring BootSwaggerRESTAPI
- Holer實現外網訪問本地RESTful APIRESTAPI
- 使用Golang建立RESTful API的最佳實踐案例GolangRESTAPI
- 每天用SpringBoot，還不懂RESTful API返回統一資料格式是怎麼實現的？Spring BootRESTAPI
- springboot整合swagger2Spring BootSwagger
- 安全優雅的RESTful API簽名實現方案RESTAPI
- RESTful API實踐總結RESTAPI
- k8s ：kube-apiserver RESTful API 實現 - StorageK8SAPIServerREST
- Yii2.0 實現RESTful風格的簡單APIRESTAPI
- 使用 dynamic 型別讓 ASP.NET Core 實現 HATEOAS 結構的 RESTful API型別ASP.NETRESTAPI
- 使用靜態基類方案讓 ASP.NET Core 實現遵循 HATEOAS Restful Web APIASP.NETRESTWebAPI
- 使用Golang和MongoDB構建 RESTful APIGolangMongoDBRESTAPI
- 使用 swoole 加速 Larave Restful API 介面（1）RESTAPI
- [實戰] 使用 MongoDB Go 驅動與 Iris 構建 RESTful APIMongoDBRESTAPI
- 理解RESTful APIRESTAPI
- .NET雲原生應用實踐（二）：Sticker微服務RESTful API的實現微服務RESTAPI
- 使用 swoole 加速 Lumen5.7 Restful API 介面RESTAPI
- 使用 swoole 加速 Laravel5.6 Restful API 介面LaravelRESTAPI
- SAP Marketing Cloud Restful API SDK 使用案例分享CloudRESTAPI
- Django RESTful API設計與實踐指南DjangoRESTAPI
- RESTful風格APIRESTAPI
- 線上API介面文件swagger2APISwagger
- Gin與Mysql實現簡單Restful風格API實戰示例詳解PRHCMySqlRESTAPI
- SpringBoot2 整合 Swagger2文件 使用BootstrapUI頁面Spring BootSwaggerUI