深入理解 Swagger 注解 @API、@ApiOperation 和 @ApiParam

本文将深入介绍 Swagger 常见注解 @API、@ApiOperation 和 @ApiParam,解释它们的作用和用法。

用 Apifox,节省研发团队的每一分钟

深入理解 Swagger 注解 @API、@ApiOperation 和 @ApiParam

免费使用 Apifox

相关推荐

最新文章

API

一体化协作平台

API 设计

API 文档

API 调试

自动化测试

API Mock

API Hub

立即体验 Apifox
目录

Java 中 Swagger 常用注解有哪些?

@ApiOperation

使用于在方法上,用于描述一个 API 的操作,例如 HTTP 请求方法、URL 路径、参数、响应等信息。该注解的参数包括 value、notes、response、responseContainer 等,分别用于描述操作的名称、说明、响应格式、响应容器等信息。以下几个比较常用:

  • value —— 用于方法描述
  • notes —— 用于提示内容
  • tags —— 可以重新分组(视情况而用)

@ApiParam

用于描述一个 API 的参数,例如参数名称、参数类型、参数描述等信息。该注解的参数包括 name、value、dataType、required、defaultValue 等,分别用于描述参数的名称、说明、数据类型、是否必需、默认值等信息。

  • name —— 参数名
  • value —— 参数说明
  • required —— 是否必填

@ApiModel()

用于描述一个数据模型,例如数据模型的名称、描述、属性等信息。该注解的参数包括 value、description、parent 等,分别用于描述数据模型的名称、说明和父类等信息。

  • value —— 表示对象名
  • description —— 描述

@ApiModelProperty()

用于描述一个数据模型的属性,例如属性名称、属性类型、属性描述等信息。该注解的参数包括 value、dataType、required、example 等,分别用于描述属性的说明、数据类型、是否必需、示例值等信息。

  • value —— 字段说明
  • name —— 重写属性名字
  • dataType —— 重写属性类型
  • required —— 是否必填
  • example —— 举例说明
  • hidden —— 隐藏

代码示例

@RequestMapping(
    method = RequestMethod.POST,
    value = "/createUser",
    produces = "application/json; charset=UTF-8")@ResponseStatus(HttpStatus.CREATED)@ResponseBody@ApiOperation(value = "Create user",
  notes = "This method creates a new user")public User createUser(
  @ApiParam(
    name =  "firstName",
    type = "String",
    value = "First Name of the user",
    example = "Vatsal",
    required = true)@RequestParam String firstName) {
 
    User user = new User(firstName);
    return user;
}Copy
Swagger
Swagger

更好的选择

如果注解的作用范围很广,那么它们可能会让代码更加难以维护。当需要对代码进行修改时,可能需要花费更多的时间来确保注解的正确性。可能会隐藏代码的本质:如果注解被用于隐藏代码的本质,那么它们可能会让代码更加难以理解。例如,在使用某些框架时,注解可能会隐藏框架的内部工作原理,使得代码更加难以理解。

对于 Java 项目我们可以使用优秀的 Swagger 工具,这帮助我们处理了输出 API 文档的逻辑,对于不满足于这种场景推荐使用 Apifox, 使用 Apifox 无需编写代码,通过直观的可视化的操作我们就可以设计 API, 只要你会使用 JSON。使用 Apifox 设计符合的工作方式,无需发布部署就能让同事们 review 并评论。

  1. 需编写代码:使用 Apifox,你可以通过简单的拖放和单击操作,创建 API 设计图,而不需要编写任何代码。这样可以大大降低 API 设计的门槛,让更多的人可以参与 API 设计。
  2. 简化 API 设计过程:Apifox 提供了丰富的 API 设计工具和预定义的 API 组件,可以帮助你快速构建 API 设计图。这样可以使 API 设计过程更加高效、准确,减少错误和重复工作。
  3. 方便团队协作:Apifox 可以将 API 设计图保存在云端,可以轻松地与团队成员共享和协作。这样可以加快 API 设计的进程,同时也可以避免版本控制问题。
深入理解 Swagger 注解

知识扩展: