隨著互聯(lián)網(wǎng)技術的發(fā)展，現(xiàn)在的網(wǎng)站架構基本都由原來的后端渲染，變成了：前端渲染、先后端分離的形態(tài)，而且前端技術和后端技術在各自的道路上越走越遠。
這樣后段開發(fā)好了api 之后就要提交api 文檔給前端的朋友。給前端的api 文檔各個公司有各個公司的要求，有的是word 有的是 md 文檔，或者是 postman 的一個連接。
好了廢話不多說說一下 swagger -ui 吧
什么是swagger
swagger是一個restful風格接口的文檔在線自動生成和測試的框架
官網(wǎng)：http://swagger.io
官方描述：the world's most popular framework for apis.
先看一下 swagger-ui 生成的api 的效果吧（這是一個增刪改查的小李子）
然后我們打開查詢所有用戶的api 看到api 內容
然后在服務器運行的狀態(tài)下點擊 try it out 測試查詢功能
接著打開新增的api 查看
好了這個就是自動生成的api 效果。接下來我們就看怎么在我們的項目中使用swagger-ui 吧
springboot 集成 swagger -ui
1、添加依賴
<dependency>
<groupid>io.springfox</groupid>
<artifactid>springfox-swagger2</artifactid>
<version>2.2.2</version>
</dependency>
<dependency>
<groupid>io.springfox</groupid>
<artifactid>springfox-swagger-ui</artifactid>
<version>2.2.2</version>
</dependency>
2、編寫配置文件
在application 同級目錄新建 swagger2 文件
package com.abel.example;
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;
/**
* created by yangyibo on 2018/9/7.
*/
@configuration
@enableswagger2
public class swagger2 {
/**
* 創(chuàng)建api應用
* apiinfo() 增加api相關信息
* 通過select()函數(shù)返回一個apiselectorbuilder實例,用來控制哪些接口暴露給swagger來展現(xiàn)，
* 本例采用指定掃描的包路徑來定義指定要建立api的目錄。
* @return
*/
@bean
public docket createrestapi() {
return new docket(documentationtype.swagger_2)
.apiinfo(apiinfo())
.select()
.apis(requesthandlerselectors.basepackage("com.abel.example.controller"))
.paths(pathselectors.any())
.build();
}
/**
* 創(chuàng)建該api的基本信息（這些基本信息會展現(xiàn)在文檔頁面中）
* 訪問地址：http://項目實際地址/swagger-ui.html
* @return
*/
private apiinfo apiinfo() {
return new apiinfobuilder()
.title("spring boot中使用swagger2構建restful apis")
.description("更多請關注https://blog.csdn.net/u012373815")
.termsofserviceurl("https://blog.csdn.net/u012373815")
.contact("abel")
.version("1.0")
.build();
}
}
3、在controller上添加注解，自動生成api
注意：
package com.abel.example.controller;
import javax.servlet.http.httpservletrequest;
import java.util.map;
import com.abel.example.bean.user;
import io.swagger.annotations.*;
import org.apache.log4j.logger;
import org.springframework.beans.factory.annotation.autowired;
import org.springframework.http.httpstatus;
import org.springframework.http.responseentity;
import org.springframework.stereotype.controller;
import org.springframework.web.bind.annotation.*;
import com.abel.example.service.userservice;
import com.abel.example.util.commonutil;
@controller
@requestmapping(value = "/users")
@api(value = "用戶的增刪改查")
public class usercontroller {
@autowired
private userservice userservice;
/**
* 查詢所有的用戶
* api :localhost:8099/users
* @return
*/
@requestmapping(method = requestmethod.get)
@responsebody
@apioperation(value = "獲取用戶列表，目前沒有分頁")
public responseentity<object> findall() {
return new responseentity<>(userservice.listusers(), httpstatus.ok);
}
/**
* 通過id 查找用戶
* api :localhost:8099/users/1
* @param id
* @return
*/
@requestmapping(value = "/{id}", method = requestmethod.get)
@responsebody
@apioperation(value = "通過id獲取用戶信息", notes="返回用戶信息")
public responseentity<object> getuserbyid(@pathvariable integer id) {
return new responseentity<>(userservice.getuserbyid(long.valueof(id)), httpstatus.ok);
}
/**
* 通過spring data jpa 調用方法
* api :localhost:8099/users/byname?username=xxx
* 通過用戶名查找用戶
* @param request
* @return
*/
@requestmapping(value = "/byname", method = requestmethod.get)
@responsebody
@apiimplicitparam(paramtype = "query",name= "username" ,value = "用戶名",datatype = "string")
@apioperation(value = "通過用戶名獲取用戶信息", notes="返回用戶信息")
public responseentity<object> getuserbyusername(httpservletrequest request) {
map<string, object> map = commonutil.getparametermap(request);
string username = (string) map.get("username");
return new responseentity<>(userservice.getuserbyusername(username), httpstatus.ok);
}
/**
* 通過spring data jpa 調用方法
* api :localhost:8099/users/byusernamecontain?username=xxx
* 通過用戶名模糊查詢
* @param request
* @return
*/
@requestmapping(value = "/byusernamecontain", method = requestmethod.get)
@responsebody
@apiimplicitparam(paramtype = "query",name= "username" ,value = "用戶名",datatype = "string")
@apioperation(value = "通過用戶名模糊搜索用戶信息", notes="返回用戶信息")
public responseentity<object> getusers(httpservletrequest request) {
map<string, object> map = commonutil.getparametermap(request);
string username = (string) map.get("username");
return new responseentity<>(userservice.getbyusernamecontaining(username), httpstatus.ok);
}
/**
* 添加用戶啊
* api :localhost:8099/users
* @param user
* @return
*/
@requestmapping(method = requestmethod.post)
@responsebody
@apimodelproperty(value="user",notes = "用戶信息的json串")
@apioperation(value = "新增用戶", notes="返回新增的用戶信息")
public responseentity<object> saveuser(@requestbody user user) {
return new responseentity<>(userservice.saveuser(user), httpstatus.ok);
}
/**
* 修改用戶信息
* api :localhost:8099/users
* @param user
* @return
*/
@requestmapping(method = requestmethod.put)
@responsebody
@apimodelproperty(value="user",notes = "修改后用戶信息的json串")
@apioperation(value = "新增用戶", notes="返回新增的用戶信息")
public responseentity<object> updateuser(@requestbody user user) {
return new responseentity<>(userservice.updateuser(user), httpstatus.ok);
}
/**
* 通過id刪除用戶
* api :localhost:8099/users/2
* @param id
* @return
*/
@requestmapping(value = "/{id}", method = requestmethod.delete)
@responsebody
@apioperation(value = "通過id刪除用戶信息", notes="返回刪除狀態(tài)1 成功 0 失敗")
public responseentity<object> deleteuser(@pathvariable integer id) {
return new responseentity<>(userservice.removeuser(id.longvalue()), httpstatus.ok);
}
}
注解含義：
@api：用在類上，說明該類的作用。 @apioperation：注解來給api增加方法說明。 @apiimplicitparams : 用在方法上包含一組參數(shù)說明。 @apiimplicitparam：用來注解來給方法入?yún)⒃黾诱f明。 @apiresponses：用于表示一組響應 @apiresponse：用在@apiresponses中，一般用于表達一個錯誤的響應信息 code：數(shù)字，例如400 message：信息，例如"請求參數(shù)沒填好" response：拋出異常的類 @apimodel：描述一個model的信息（一般用在請求參數(shù)無法使用@apiimplicitparam注解進行描述的時候） @apimodelproperty：描述一個model的屬性
注意：@apiimplicitparam的參數(shù)說明：
paramtype會直接影響程序的運行期，如果paramtype與方法參數(shù)獲取使用的注解不一致，會直接影響到參數(shù)的接收。
4、啟動項目效果圖：
服務器啟動后訪問 http://localhost:8099/swagger-ui.html 效果如下
點擊查看效果
本文項目全部代碼：https://github.com/527515025/springboot/tree/master/springboot-swagger-ui
總結
以上就是這篇文章的全部內容了，希望本文的內容對大家的學習或者工作具有一定的參考學習價值，謝謝大家對服務器之家的支持。如果你想了解更多相關內容請查看下面相關鏈接
原文鏈接：https://blog.csdn.net/u012373815/article/details/82685962
