Swagger中的常用注解

1、简介

Swagger是为了解决企业中接口（api）中定义统一标准规范的文档生成工具。很多采用前后端分离的模式，前端只负责调用接口，进行渲染，前端和后端的唯一联系，变成了API接口。因此，API文档变得越来越重要。swagger是一个方便我们更好的编写API文档的框架，而且swagger可以模拟http请求调用。

2、常用注解与示例

@Api（）用于类：表示标识这个类是swagger的资源

@Api("用于类") @Controller public class swaggerTest(){ }

@ApiOperation（）用于方法：表示一个http请求的操作

@Api("ApiOperation测试") @Controller public class swaggerTest(){ @ApiOperation(value = "apiOperationTest", notes = "apiOperation测试") public void apiOperationSwaggerTest(){ } }

@ApiParam（）：用于方法，参数，字段说明：表示对参数的添加元数据（说明或是否必填等）

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

@ApiModel（）用于类：表示对类进行说明，用于参数用实体类接收

@ApiModel(description = "实体类", value = "实体类") public class City implements Serializable { }

@ApiModelProperty（）用于方法，字段：表示对model属性的说明或者是数据操作更改

@ApiModel(description = "实体类", value = "实体类") public class City implements Serializable { @ApiModelProperty(name = "id", value = "编号", required = false, exmaple = "1") private int id; }

@ApiIgnore（）用于类，方法，方法参数：表示这个方法或者类被忽略

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

@ApiImplicitParam（）用于方法：表示单独的请求参数

@ApiImplicitParams（）用于方法，包含多个@ApiImplicitParam

@Api("测试1") @Controller public class swaggerTest(){ @ApiOperation(value = "apiOperationTest", notes = "apiOperation测试") @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){ } }

实例

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; /** * 调用权限接口 * * @author Promsing(张有博) * @version 1.0.0 * @since 2021/12/18 - 11:39 */ @Api(tags = {"调用权限接口"}) @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

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。