Java中Swagger框架的使用詳解
更新時間:2023年08月30日 11:06:02 作者:余生海
這篇文章主要介紹了Java框架Swagger的使用詳解,在開發(fā)期間接口會因業(yè)務(wù)的變更頻繁而變動,如果需要實時更新接口文檔,這是一個費時費力的工作,Swagger應(yīng)運而生,他可以輕松的整合進框架并通過一系列注解生成強大的API文檔,需要的朋友可以參考下
簡介
- 由于架構(gòu)革新,進入了前后端分離,服務(wù)端只需提供RESTful API的時代。
- 而構(gòu)建RESTful API會考慮到多終端的問題,這樣就需要面對多個開發(fā)人員甚至多個開發(fā)團隊。
- 為了減少與其他團隊對接的溝通成本,我們通常會寫好對應(yīng)的API接口文檔。
- 從最早開始的word文檔,到后續(xù)的showdoc,都能減少很多溝通成本,但隨之帶來的問題也比較麻煩。在開發(fā)期間接口會因業(yè)務(wù)的變更頻繁而變動,如果需要實時更新接口文檔,這是一個費時費力的工作。
- 為了解決上面的問題,Swagger應(yīng)運而生。他可以輕松的整合進框架,并通過一系列注解生成強大的API文檔。他既可以減輕編寫文檔的工作量,也可以保證文檔的實時更新,將維護文檔與修改代碼融為一體,是目前較好的解決方案。
常用注解
- @Api()用于類;
- 表示標(biāo)識這個類是swagger的資源
- @ApiOperation()用于方法;
- 表示一個http請求的操作
- @ApiParam()用于方法,參數(shù),字段說明;
- 表示對參數(shù)的添加元數(shù)據(jù)(說明或是否必填等)
- @ApiModel()用于類
- 表示對類進行說明,用于參數(shù)用實體類接收
- @ApiModelProperty()用于方法,字段
- 表示對model屬性的說明或者數(shù)據(jù)操作更改
- @ApiIgnore()用于類,方法,方法參數(shù)
- 表示這個方法或者類被忽略
- @ApiImplicitParam() 用于方法
- 表示單獨的請求參數(shù)
- @ApiImplicitParams() 用于方法,包含多個 @ApiImplicitParam
代碼示例
- @Api
@Api(value = "用戶博客", tags = "博客接口")
public class NoticeController {
}- @ApiOperation
@GetMapping("/detail")
@ApiOperation(value = "獲取用戶詳細(xì)信息", notes = "傳入notice")
public R<Notice> detail(Integer id) {
Notice detail = noticeService.getOne(id);
return R.data(detail );
}- @ApiResponses
@GetMapping("/detail")
@ApiOperation(value = "獲取用戶詳細(xì)信息", notes = "傳入notice")
@ApiResponses(value = {@ApiResponse(code = 500, msg= "INTERNAL_SERVER_ERROR", response = R.class)})
public R<Notice> detail(Integer id) {
Notice detail = noticeService.getOne(id);
return R.data(detail );
}- @ApiImplicitParams
@GetMapping("/list")
@ApiImplicitParams({
@ApiImplicitParam(name = "category", value = "公告類型", paramType = "query", dataType = "integer"),
@ApiImplicitParam(name = "title", value = "公告標(biāo)題", paramType = "query", dataType = "string")
})
@ApiOperation(value = "分頁", notes = "傳入notice")
public R<IPage<Notice>> list(@ApiIgnore @RequestParam Map<String, Object> notice, Query query) {
IPage<Notice> pages = noticeService.page(Condition.getPage(query), Condition.getQueryWrapper(notice, Notice.class));
return R.data(pages );
}- @ApiParam
@PostMapping("/remove")
@ApiOperation(value = "邏輯刪除", notes = "傳入notice")
public R remove(@ApiParam(value = "主鍵集合") @RequestParam String ids) {
boolean temp = noticeService.deleteLogic(Func.toIntList(ids));
return R.status(temp);
}- @ApiModel 與 @ApiModelProperty
@Data
@ApiModel(value = "BladeUser ", description = "用戶對象")
public class BladeUser implements Serializable {
private static final long serialVersionUID = 1L;
@ApiModelProperty(value = "主鍵", hidden = true)
private Integer userId;
@ApiModelProperty(value = "昵稱")
private String userName;
@ApiModelProperty(value = "賬號")
private String account;
@ApiModelProperty(value = "角色id")
private String roleId;
@ApiModelProperty(value = "角色名")
private String roleName;
}- @ApiIgnore()
@ApiIgnore()
@GetMapping("/detail")
public R<Notice> detail(Integer id) {
Notice detail = noticeService.getOne(id);
return R.data(detail );
}到此這篇關(guān)于Java中間件Swagger的使用詳解的文章就介紹到這了,更多相關(guān)Swagger的使用內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家!
相關(guān)文章
用Java設(shè)計模式中的觀察者模式開發(fā)微信公眾號的例子
這篇文章主要介紹了用Java設(shè)計模式中的觀察者模式開發(fā)微信公眾號的例子,這里Java的微信SDK等部分便不再詳述,只注重關(guān)鍵部分和開發(fā)過程中觀察者模式優(yōu)點的體現(xiàn),需要的朋友可以參考下2016-02-02
Java IO三大模型(BIO/NIO/AIO)的使用總結(jié)
相信很多Java開發(fā)剛接觸IO模型時,都會被「BIO、NIO、AIO」「同步、異步、阻塞、非阻塞」這些概念繞暈,下面就來詳細(xì)的介紹一下 IO三大模型的使用,感興趣的可以了解一下2026-02-02
Spring處理@Async導(dǎo)致的循環(huán)依賴失敗問題的方案詳解
這篇文章主要為大家詳細(xì)介紹了SpringBoot中的@Async導(dǎo)致循環(huán)依賴失敗的原因及其解決方案,文中的示例代碼講解詳細(xì),感興趣的可以學(xué)習(xí)一下2022-07-07
springboot+vue實現(xiàn)Token自動續(xù)期(雙Token方案)
雙Token方案通過訪問令牌和刷新令牌提高用戶登錄安全性和體驗,訪問令牌有效期短,包含用戶信息,用于請求校驗,本文就來介紹一下springboot+vue實現(xiàn)Token自動續(xù)期(雙Token方案),感興趣的可以了解一下2024-10-10

