Swagger常用注解

关注

原创最新推荐文章于 2026-03-19 22:27:50 发布 2k 阅读 AI 写同款· GEO 优化 ›

swagger常用注解 Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使文档成为项目的一部分，使文档与代码保持同步。为了达到这个目标，Swagger 允许开发者通过注解（Annotation）的方式来定义接口的相关信息。阅读详情

目前项目已经替换为knife4j了：https://www.jianshu.com/p/48d9473de9c8（个人比较喜欢knife4j的ui风格，而且用起来比较方便）

下面介绍一些在开发过程中通常用的Swagger注解。

1、@Api

说明每个controller层控制类的作用，即每个请求类
属性：tags：描述该类的作用

2、@RestController

它是复合注解，代表的是一个控制器，由于它同时拥有@Controller和@ResponseBody的作用，所在如果要返回JSON数据，则不需要在方法上面加@ResponseBody注解，但是它不能返回jsp、html页面

3、@RequestMapping、@GetMapping、@PostMapping、@PutMapping、@DeleteMapping

定义前端访问的url，可以写在控制类上，也可以写在控制类汇总的方法上面，常用的的写在控制类上面，一般会与它的衍生注解组合使用：
@GetMapping 查询请求
@PostMapping 添加请求
@PutMapping 修改请求
@DeleteMapping 删除请求

4、@ApiOperation

作用在控制类中的每个方法上，说明该类的作用
value：说明该类的作用
notes：详细说明
以上这几个注解在代码中的使用例子如下：

/**
 * Description: 立案审批
 *
 * @author ZhuZiKai
 * @date 2019/9/13 0013
 */
@Api(tags = {"立案受理"})
@RestController
@RequestMapping(value = "/case")
public class AcceptanceController extends BaseController {
    @Autowired
    private AcceptanceService acceptanceService;
    @Autowired
    private AsyncTask asyncTask;
    @Autowired
    private BaseStatisticsImpl baseStatistics;
    
    @ApiOperation(value = "案件基本信息录入",notes="")
    @PostMapping(value = "/acceptance/inputBaseInfo")
    public BaseResp inputBaseInfo(@ApiParam(value = "案件受理对象", required = false) Acceptance acceptance) {

swagger-ui展示结果如下：
在这里插入图片描述

5、@ApiParam

@ApiParam作用于请求方法上，定义api参数的注解，属性有：
name：api参数的英文名
value：api参数的描述
required：true表示参数必输，false标识参数非必输，默认为非必输
此注解通常与@RequestParam或者@PathVariable集合使用，因为它的作用只是定义每个参数（因此可以不使用，但是为了方便测试，加上效果更好），如果要获取前端的参数还需要通过@RequestParam或者@PathVariable来获取

6、@PathVariable

获取get请求url路径上的参数，即参数绑定的作用，通俗的说是url中"?"前面绑定的参数
代码示例：

/**
     * 根据案件Id获取案件
     * @param caseId 案件编号
     * @return
     */
    @GetMapping(value = "/Close/getCases/{caseId}")
    public BaseResp getCases(@ApiParam(name = "String", value = "案件编号", required = true) @PathVariable("caseId") String caseId) {
        Admin currentUser = findCurrentUser();
        List<PageData> caseApprovals = closeService.getCases(currentUser, caseId);
        return new BaseResp(ResultStatus.SUCCESS, caseApprovals);
    }

测试示例：
在这里插入图片描述
请求url示例：http://127.0.0.1:8081/case/Close/getCases/2019091508
这里的获取参数的类型下面会说一下有几种形式。

7、@RequestParam

获取前端传过来的参数，可以是get、post请求，通俗的说是url中"?"后面拼接的每个参数
代码示例：

/**
     * 根据案件Id获取案件
     * @param caseId 案件编号
     * @return
     */
    @GetMapping(value = "/Close/getCases)
    public BaseResp getCases(@ApiParam(name = "String", value = "案件编号", required = true) @RequestParam("caseId") String caseId) {
        Admin currentUser = findCurrentUser();
        List<PageData> caseApprovals = closeService.getCases(currentUser, caseId);
        return new BaseResp(ResultStatus.SUCCESS, caseApprovals);
    }

测试示例：
请求url示例：http://127.0.0.1:8081/case/Close/getCases?caseId=2019091508

8、@RequestBody

@RequestBody接受的是一个json对象的字符串，而不是Json对象，在请求时往往都是Json对象，用JSON.stringify(data)的方式就能将对象变成json字符串。如果使用@RequestBody出现Content type ‘application/x-www-form-urlencoded;charset=UTF-8’ not supported 的时候。可能是如下问题
在这里插入图片描述
所以当前端传的是Json对象字符串时，后端接口用@RequestBody接收参数

 /**
     * 调查经过描述录入
     *
     * @param investigationReport
     * @return
     */
    @ApiOperation(value = "调查经过描述录入")
    @PostMapping(value = "/details/inputIllegalFacts")
    public BaseResp illegalFacts(@ApiParam(value = "案件调查终结报告对象") @RequestBody InvestigationReport investigationReport) {
        try {

这时候swagger怎么获取都对象里面每个参数的类型以及说明呢，这里介绍两个用于对象上的注解@ApiModel，@ApiModelProperty。

9、@ApiModel

@ApiModel 用在类上，表示对类进行说明，用于实体类中的参数接收说明。使用方式代码如下所示。

/**
 * Description: 案件调查终结报告
 *
 * @author ZhuZiKai
 * @date 2020/2/14 0014
 */
@Data
@Table(name = "hz_ac_investigation_report")
@ApiModel(value = "com.terabits.examinationcase.meta.po.InvestigationReport", description = "案件调查终结报告对象")
public class InvestigationReport {
}

10、@ApiModelProperty

@ApiModelProperty() 用于字段，表示对 model 属性的说明。使用方式代码如下所示。

@Data
@Table(name = "hz_ac_investigation_report")
@ApiModel(value = "com.terabits.examinationcase.meta.po.InvestigationReport", description = "案件调查终结报告对象")
public class InvestigationReport {
    @ApiModelProperty(value = "id", dataType = "Integer")
    private Integer id;

    @ApiModelProperty(value = "案件编号", dataType = "String")
    private String caseId;
    
    @ApiModelProperty(value = "主办人编号", dataType = "Integer")

    private Integer adminId;

swagger接口展示
在这里插入图片描述

11、 @ApiImplicitParams、@ApiImplicitParam

定义参数的注解除了@ApiParam之外，这两个注解也可以定义参数，一般用于对每个参数单独定义
①、@ApiImplicitParams定义一组参数
②、@ApiImplicitParam写在@ApiImplicitParams中，定义每个参数的信息，属性为：
name：参数英文名称
value：参数中文名称
paramType：调用的url 参数形式，“query”为问号"?"后面的拼接参数，“path”为绑定的参数，“header”为request请求头参数，“form”为表单提交参数，“body”为对象参数，仅支持post
代码示例：

/**
     * 结案案件查询列表
     *
     * @param caseId
     * @param beginTime
     * @param endTime
     * @param decisionBeginTime
     * @param decisionEndTime
     * @return
     */
    @ApiOperation(value = "结案案件查询列表")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", dataType = "String", name = "caseId", value = "案件id", required = false),
            @ApiImplicitParam(paramType = "query", dataType = "String", name = "beginTime", value = "结案开始时间", required = false),
            @ApiImplicitParam(paramType = "query", dataType = "String", name = "endTime", value = "结案结束时间", required = false),
            @ApiImplicitParam(paramType = "query", dataType = "String", name = "decisionBeginTime", value = "决定书寄出开始时间", required = false),
            @ApiImplicitParam(paramType = "query", dataType = "String", name = "decisionEndTime", value = "决定书寄出结束时间", required = false)
    })
    @GetMapping(value = "/case/Close/getCases")
    public BaseResp getCases(@RequestParam String caseId, @RequestParam String beginTime, @RequestParam String endTime, @RequestParam String decisionBeginTime, @RequestParam String decisionEndTime) {
        try {
            Admin currentUser = findCurrentUser();
            List<PageData> caseApprovals = closeService.getCases(currentUser, caseId, beginTime, endTime, decisionBeginTime, decisionEndTime);
            return new BaseResp(ResultStatus.SUCCESS, caseApprovals);
        } catch (Exception e) {
            EXCEPTIONLOGGER.error("", e);
        }
        return new BaseResp(ResultStatus.FAIL);
    }

测试示例：
在这里插入图片描述

@ApiImplicitParam

属性	取值	作用
paramType		查询参数类型
	path	以地址的形式提交数据
	query	直接跟参数完成自动映射赋值
	body	以流的形式提交仅支持POST
	header	参数在request headers 里边提交
	form	以form表单的形式提交仅支持POST
dataType		参数的数据类型只作为标志说明，并没有实际验证
	Long
	String
name		接收参数名
value		接收参数的意义描述
required		参数是否必填
	true	必填
false		非必填
defaultValue		默认值

@ApiImplicitParam(paramType = "query", dataType = "String", name = "caseId", value = "案件id", required = false),

paramType 示例详解

path

@RequestMapping(value = "/getCases/{id}", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
 
 @PathVariable(name = "id") Long id

body

@ApiImplicitParams({ @ApiImplicitParam(paramType = "body", dataType = "MessageParam", name = "param", value = "信息参数", required = true) })
 @RequestMapping(value = "/getCases", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE, consumes = MediaType.APPLICATION_JSON_VALUE)
 
 @RequestBody MessageParam param
 
 提交的参数是这个对象的一个json，然后会自动解析到对应的字段上去，也可以通过流的形式接收当前的请求数据，但是这个和上面的接收方式仅能使用一个（用@RequestBody之后流就会关闭了）

header

@ApiImplicitParams({ @ApiImplicitParam(paramType = "header", dataType = "Long", name = "id", value = "信息id", required = true) })
 //参数在request headers 请求头中 
  String idstr = request.getHeader("id");
       if (StringUtils.isNumeric(idstr)) {
           id = Long.parseLong(idstr);
       }

Form

@ApiImplicitParams({ @ApiImplicitParam(paramType = "form", dataType = "Long", name = "id", value = "信息id", required = true) })
 @RequestMapping(value = "/getCases", method = RequestMethod.POST, produces = MediaType.APPLICATIO

12、ApiResponse 和 ApiResponses

@ApiResponse 用于方法上，说明接口响应的一些信息；@ApiResponses 组装了多个 @ApiResponse。使用方式代码如下所示。

@ApiOperation(value = "案件基本信息录入")
    @ApiResponses({@ApiResponse(code = 200, message = "操作成功"),
            @ApiResponse(code = 400, message = "请求中有语法错误,或不能满足请求"),
            @ApiResponse(code = 401, message = "未授权客户端访问数据"),
            @ApiResponse(code = 403, message = "服务器内部异常"),
            @ApiResponse(code = 404, message = "服务器找不到给定资源;接口不存在"),
            @ApiResponse(code = 500, message = "服务器不能完成请求")
    })
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "body", dataType = "Acceptance", name = "acceptance", value = "案件受理对象", required = false)
    })
    @PostMapping(value = "/acceptance/inputBaseInfo")
    public BaseResp inputBaseInfo(@RequestBody Acceptance acceptance) {

总结：基本上日常常用注解整理一下就是这样了，如下实例：（@ApiResponses注解写在每个接口的话，个人觉得代码很臃肿，所以省略了）


/**
 * Description: 案件查询
 *
 * @author ZhuZiKai
 * @date 2019/10/14 0014
 */
@Api(tags = {"结案案件查询"})
@RestController
@RequestMapping(value = "/case")
public class CaseInfoController extends BaseController {
    @Autowired
    private CloseService closeService;

    /**
     * 结案案件查询列表
     *
     * @param caseId
     * @param decisionBeginTime
     * @param decisionEndTime
     * @return
     */
    @ApiOperation(value = "结案案件查询列表",notes = "")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", dataType = "String", name = "caseId", value = "案件编号", required = false),
            @ApiImplicitParam(paramType = "query", dataType = "String", name = "decisionBeginTime", value = "决定书寄出时间", required = false),
            @ApiImplicitParam(paramType = "query", dataType = "String", name = "decisionEndTime", value = "决定书寄出时间", required = false)
    })
    @GetMapping(value = "/Close/getCases")
    public BaseResp getCases(@RequestParam(value = "caseId") String caseId, @RequestParam(value = "decisionBeginTime") String decisionBeginTime, @RequestParam(value = "decisionEndTime") String decisionEndTime) {
        try {
            Admin currentUser = findCurrentUser();
            List<PageData> caseApprovals = closeService.getCases(currentUser, caseId, decisionBeginTime, decisionEndTime);
            return new BaseResp(ResultStatus.SUCCESS, caseApprovals);
        } catch (Exception e) {
            EXCEPTIONLOGGER.error("", e);
        }
        return new BaseResp(ResultStatus.FAIL);
    }

接收参数为json字符串，接口参数用对象接收时实例：

/**
     * 调查经过描述录入
     *
     * @param investigationReport
     * @return
     */
    @ApiOperation(value = "调查经过描述录入",notes = "")
    @PostMapping(value = "/details/inputIllegalFacts")
    public BaseResp illegalFacts(@ApiParam(value = "案件调查终结报告对象") @RequestBody InvestigationReport investigationReport) {
        try {
            Integer integer = caseInformationService.inputIllegalFacts(investigationReport);
            if (integer == 1) {
                return new BaseResp(ResultStatus.SUCCESS);
            }
            return new BaseResp(ResultStatus.FAIL);
        } catch (Exception e) {
            EXCEPTIONLOGGER.error("", e);
        }
        return new BaseResp(ResultStatus.FAIL);
    }

对象类实例

/**
 * Description: 案件调查终结报告
 *
 * @author ZhuZiKai
 * @date 2020/2/14 0014
 */
@Data
@Table(name = "hz_ac_investigation_report")
@ApiModel(value = "com.terabits.examinationcase.meta.po.InvestigationReport", description = "案件调查终结报告对象")
public class InvestigationReport {
    @ApiModelProperty(value = "id", dataType = "Integer")
    private Integer id;

    @ApiModelProperty(value = "案件编号", dataType = "String")
    private String caseid;

    @ApiModelProperty(value = "主办人编号", dataType = "Integer")

    private Integer adminid;