Swagger 注解 @ApiModel 和 @ApiModelProperty 的用法

@ApiModel 注解用于描述一个模型，可以用在类上。它的作用是给模型起一个名称和描述，方便在生成的 API 文档中展示。@ApiModelProperty 注解则用于描述模型的属性，可以用在属性上。它的作用是给属性起一个名称和描述，并提供其他相关的配置项，如示例数据、数据类型等，同样会在生成的 API 文档中展示。

@ApiModel 和 @ApiModelProperty 使用场景

使用@ApiModel 和@ApiModelProperty 注解可以方便地描述模型和模型属性，尤其适用于以下场景：

1. API 文档生成：@ApiModel 和@ApiModelProperty 注解提供了生成 API 文档所需的模型和属性信息，使得开发者能够更加方便地生成和维护 API 文档。
2. 模型验证：@ApiModelProperty 注解中的配置项可以用于对模型属性进行验证，如最大长度、最小值等，方便进行数据的合法性校验。
3. 模型展示：在生成的 API 文档中，@ApiModel 和@ApiModelProperty 注解提供的信息可以用于展示模型和属性的名称、描述、示例数据等，使得开发者和使用者更容易理解 API 的定义和使用方式。
   

@ApiModel 和 @ApiModelProperty 用法介绍

@ApiModel 注解的用法如下：

@ApiModelProperty 注解的用法如下：

实践案例

假设我们有一个用户管理系统，需要设计一个用户模型，并使用 Swagger 注解@ApiModel 和@ApiModelProperty 对其进行描述。以下是更详细的示例代码：

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(value = "User", description = "用户模型")
public class User {
    @ApiModelProperty(value = "用户ID", example = "1")
    private Long id;
    
    @ApiModelProperty(value = "用户名", example = "john.doe")
    private String username;
    
    @ApiModelProperty(value = "年龄", example = "25")
    private Integer age;
    
    // 省略其他属性的getters和setters

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getUsername() {
        return username;
    }
    
    public void setUsername(String username) {
        this.username = username;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }
}

在上述示例中，我们首先在 User 类上使用@ApiModel 注解，指定了数据模型的名称和描述。然后，我们在每个属性上使用@ApiModelProperty 注解，分别指定了属性的描述、名称、数据类型和示例值。

使用这些注解后，在生成 API 文档时，Swagger 会自动解析这些注解，并将属性的详细信息包括在文档中。例如，生成的 API 文档会显示用户模型的名称、描述以及每个属性的名称、描述、数据类型和示例值。

在实际项目中，你可以按照这个示例的方式来使用@ApiModel 和@ApiModelProperty 注解，定义自己的数据模型，并根据需要添加其他属性和注解。通过这种方式，你可以更好地描述和展示数据模型，并生成清晰明了的 API 文档。

注意事项

在使用@ApiModel 和@ApiModelProperty 注解时，需要注意以下事项：

• 需要引入对应的 Swagger 依赖，并进行正确的配置。
• 注解的属性配置要正确，如名称、描述、数据类型等。
• 在模型属性上使用@ApiModelProperty 注解时，要保证属性的访问权限是公开的，即提供对应的 getter 和 setter 方法。
  
  

常见问题及解决方法

Q1: 是否可以在同一个模型中使用多个@ApiModel 注解？

A1: 不可以，一个模型只能使用一个@ApiModel 注解。

Q2: 是否可以在模型属性上使用多个@ApiModelProperty 注解？

A2: 可以，一个属性可以使用多个@ApiModelProperty 注解，用于提供不同的描述和配置。

Swagger 和 Apifox 整合

Swagger 管理接口有时很不方便，缺乏一定的安全性和团队间的分享协作，所以我更推荐使用 Apifox 的 IDEA 插件。你可以在 IDEA 中自动同步 Swagger 注解到 Apifox，一键生成接口文档，多端同步，非常方便测试和维护，这样就可以迅速分享 API 给其他小伙伴。

Apifox 是一个比 Postman 更强大的接口测试工具，Apifox = Postman + Swagger + Mock + JMeter，Apifox 支持调试 http（s）、WebSocket、Socket、gRPC、Dubbo 等协议的接口，并且集成了 IDEA 插件。

Apifox 的 IDEA 插件可以自动解析代码注释，并基于 Javadoc、KDoc 和 ScalaDoc 生成 API 文档。通过 IntelliJ IDEA 的 Apifox Helper 插件，开发人员可以在不切换工具的情况下将他们的文档与 Apifox 项目同步。

当在 IDEA 项目中有接口信息变动，只需右键点击「 Upload to Apifox」一键即可完成同步，无需奔走相告。团队成员可在 Apifox 中看到同步后的最新内容。

现在出发去 JetBrains 插件市场 下载试试吧！或直接在 IDEA 内 「plugin」入口直接搜索 Apifox Helper。

知识扩展：

• Swagger 注解 @ApiResponses 和 @ApiResponse 的用法
• Swagger 注解 @ApiImplicitParams 和 @ApiImplicitParam 的用法

参考链接：

• Swagger 官方文档：https://swagger.io/docs/specification/data-models/
• SpringFox 官方文档：https://springfox.github.io/springfox/docs/current/