Swagger中的常用注解

1、簡(jiǎn)介

Swagger是為了解決企業(yè)中接口（api）中定義統(tǒng)一標(biāo)準(zhǔn)規(guī)范的文檔生成工具。很多采用前后端分離的模式，前端只負(fù)責(zé)調(diào)用接口，進(jìn)行渲染，前端和后端的唯一聯(lián)系，變成了API接口。因此，API文檔變得越來(lái)越重要。swagger是一個(gè)方便我們更好的編寫(xiě)API文檔的框架，而且swagger可以模擬http請(qǐng)求調(diào)用。

2、常用注解與示例

@Api（）用于類(lèi)：表示標(biāo)識(shí)這個(gè)類(lèi)是swagger的資源

@Api("用于類(lèi)") @Controller public class swaggerTest(){ }

@ApiOperation（）用于方法：表示一個(gè)http請(qǐng)求的操作

@Api("ApiOperation測(cè)試") @Controller public class swaggerTest(){ @ApiOperation(value = "apiOperationTest", notes = "apiOperation測(cè)試") public void apiOperationSwaggerTest(){ } }

@ApiParam（）：用于方法，參數(shù)，字段說(shuō)明：表示對(duì)參數(shù)的添加元數(shù)據(jù)（說(shuō)明或是否必填等）

@Api("ApiParam測(cè)試") @Controller public class swaggerTest(){ @ApiOperation(value = "apiOperationTest", notes = "apiOperation測(cè)試") public void apiOperationTest(@ApiParam(name = "id", value = "1", required = true) Integer id){ } }

@ApiModel（）用于類(lèi)：表示對(duì)類(lèi)進(jìn)行說(shuō)明，用于參數(shù)用實(shí)體類(lèi)接收

@ApiModel(description = "實(shí)體類(lèi)", value = "實(shí)體類(lèi)") public class City implements Serializable { }

@ApiModelProperty（）用于方法，字段：表示對(duì)model屬性的說(shuō)明或者是數(shù)據(jù)操作更改

@ApiModel(description = "實(shí)體類(lèi)", value = "實(shí)體類(lèi)") public class City implements Serializable { @ApiModelProperty(name = "id", value = "編號(hào)", required = false, exmaple = "1") private int id; }

@ApiIgnore（）用于類(lèi)，方法，方法參數(shù)：表示這個(gè)方法或者類(lèi)被忽略

@ApiIgnore @Api(tags = {"Xxx控制類(lèi)"}) @RestController @RequestMapping("/xxx") public class XxxController { }

@ApiImplicitParam（）用于方法：表示單獨(dú)的請(qǐng)求參數(shù)

@ApiImplicitParams（）用于方法，包含多個(gè)@ApiImplicitParam

@Api("測(cè)試1") @Controller public class swaggerTest(){ @ApiOperation(value = "apiOperationTest", notes = "apiOperation測(cè)試") @ApiImplicitParams({@ApiImplicitParam(name = "id", value = "id", required = true, dataType = "Integer", paramType = "query"), @ApiImplicitParam(name = "name", value = "name", required = true, dataType = "String", paramType = "query") }) public void apiOperationSwaggerTest(Integer id, String name){ } }

實(shí)例

package com.tfjybj.integral.provider.controller; import com.dmsdbj.cloud.tool.business.IntegralResult; import com.tfjybj.integral.model.AuthLoginModel; import com.tfjybj.integral.model.DingCodeLoginModel; import com.tfjybj.integral.provider.service.AuthService; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; /** * 調(diào)用權(quán)限接口 * * @author Promsing(張有博) * @version 1.0.0 * @since 2021/12/18 - 11:39 */ @Api(tags = {"調(diào)用權(quán)限接口"}) @RequestMapping(value = "/authController") @RestController public class AuthController { @Autowired private AuthService authService; @ApiOperation(value = "登錄") @PostMapping("login") public IntegralResult authLogin(@RequestBody AuthLoginModel authLoginModel){ Object integralResult = authService.authLogin(authLoginModel); if (integralResult==null){ return IntegralResult.build(IntegralResult.FAIL,"用戶不存在",integralResult); } return IntegralResult.build(IntegralResult.SUCCESS,"返回成功",integralResult); } @ApiOperation(value = "免密碼登錄") @PostMapping("dingCodeLogin") public IntegralResult dingCodeLogin(@RequestBody DingCodeLoginModel dingCodeLoginModel){ Object integralResult = authService.dingCodeLogin(dingCodeLoginModel); if (integralResult==null){ return IntegralResult.build(IntegralResult.FAIL,"用戶不存在",integralResult); } return IntegralResult.build(IntegralResult.SUCCESS,"返回成功",integralResult); } }

：

API

版權(quán)聲明：本文內(nèi)容由網(wǎng)絡(luò)用戶投稿，版權(quán)歸原作者所有，本站不擁有其著作權(quán)，亦不承擔(dān)相應(yīng)法律責(zé)任。如果您發(fā)現(xiàn)本站中有涉嫌抄襲或描述失實(shí)的內(nèi)容，請(qǐng)聯(lián)系我們jiasou666@gmail.com 處理，核實(shí)后本網(wǎng)站將在24小時(shí)內(nèi)刪除侵權(quán)內(nèi)容。