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
更好的选择
如果注解的作用范围很广，那么它们可能会让代码更加难以维护。当需要对代码进行修改时，可能需要花费更多的时间来确保注解的正确性。可能会隐藏代码的本质：如果注解被用于隐藏代码的本质，那么它们可能会让代码更加难以理解。例如，在使用某些框架时，注解可能会隐藏框架的内部工作原理，使得代码更加难以理解。
对于 Java 项目我们可以使用优秀的 Swagger 工具，这帮助我们处理了输出 API 文档的逻辑，对于不满足于这种场景推荐使用 Apifox, 使用 Apifox 无需编写代码，通过直观的可视化的操作我们就可以设计 API, 只要你会使用 JSON。使用 Apifox 设计符合的工作方式，无需发布部署就能让同事们 review 并评论。
- 需编写代码：使用 Apifox，你可以通过简单的拖放和单击操作，创建 API 设计图，而不需要编写任何代码。这样可以大大降低 API 设计的门槛，让更多的人可以参与 API 设计。
- 简化 API 设计过程：Apifox 提供了丰富的 API 设计工具和预定义的 API 组件，可以帮助你快速构建 API 设计图。这样可以使 API 设计过程更加高效、准确，减少错误和重复工作。
- 方便团队协作：Apifox 可以将 API 设计图保存在云端，可以轻松地与团队成员共享和协作。这样可以加快 API 设计的进程，同时也可以避免版本控制问题。
