@ApiParam详解：用注解玩转API参数，让接口文档更清晰！🏆本文收录于「滚雪球学SpringBoot」(全网一个

🏆本文收录于「滚雪球学SpringBoot」(全网一个名)专栏，希望能够助你一臂之力，帮你早日登顶实现财富自由🚀；同时，欢迎大家关注&&收藏&&订阅！持续更新中，up！up！up！！

前言

哈喽，各位同学们！早上好，本期我们要聊的是 Swagger 中的一个超级实用小注解——@ApiParam。不知道你有没有在开发 API 时，曾因接口文档的模糊不清而被前端同事“吐槽”？又或者因为参数描述不足，后端同事对接起来也容易犯迷糊？别担心，Swagger 组件它就为我们量身打造为解决业务痛点想到了这些，从而研发了 @ApiParam 注解，它就是为了解决这些问题而生的！它可以帮我们在接口文档中提供详细的参数信息，清晰地描述每一个参数的作用，让前后端沟通更顺畅，开发过程更流畅。

今天我们将从基础到进阶，带大家全面了解 @ApiParam 的用法，一起来深入交流一下吧！💡

📚 目录

🤔 为什么选择 @ApiParam？
🔍 @ApiParam 是什么？作用是什么？
🛠 @ApiParam 的常用属性及详细解析
💼 实战演示：如何在项目中使用 @ApiParam
🚀 扩展：如何结合其他注解优化接口文档
🎉 结语：让你的接口文档更智能更美观！

正文

🤔 为什么选择 `@ApiParam`？

首先我要解答下大家的疑问，为啥会选择Swagger？我们都了解一个真相，在开发 RESTful API 时，接口文档是前后端沟通的桥梁。优秀的文档可以让接口的输入输出一目了然，从而提升开发效率避免过多接口对接时间。然而，如果你的文档写得不清不楚，参数描述不足或者内容不准确，就容易造成沟通障碍，大大降低开发效率。@ApiParam 注解正是为了简化文档编写而生，它允许我们开发者直接在代码中为每个参数添加说明，让参数描述和代码紧密结合，避免了文档与代码脱节的问题。

使用 @ApiParam 注解后，Swagger 会自动生成详细的参数描述，让 API 用户一眼就能明白每个参数的含义及用途。这不仅让我们的接口文档更清晰，还能减少沟通中的“摩擦”。在这个信息高速传递的时代，高效沟通就是生产力，而 @ApiParam 就是帮助我们实现高效沟通的“神器”之一！有木有？？

例如如下代码演示：

🔍 `@ApiParam` 是什么？作用是什么？

接着，我们还要搞清楚一个理念，@ApiParam 是 Swagger 提供的一个注解，用于描述 API 接口的参数信息。通过这个注解，我们可以给 API 的每一个参数添加详细的说明，包括参数的用途、默认值、是否必填等，让接口文档更加完善、清晰。具体来说，@ApiParam 能在 Swagger UI 中展示参数的各种信息，使得前端同事或其他 API 使用者能够更加轻松地理解接口。

@ApiParam 通常和控制器中的方法参数结合使用。无论是 GET 还是 POST 请求，只要涉及到参数传递，都可以使用 @ApiParam 注解进行参数说明。它可以描述参数的类型、是否必填、默认值等，帮助开发者在代码中更加清晰地定义接口参数。

🛠 `@ApiParam` 的常用属性及详细解析

为了让大家更好地理解 @ApiParam，我们来看看它的几个常用属性，以及它们的具体作用。

value：用来简要描述参数的作用和用途。
required：标识参数是否必填，布尔值（true 或 false），默认为 false。
defaultValue：指定参数的默认值，当参数没有传递时，使用这个默认值。
allowableValues：限定参数的允许值范围，可以指定一个数组或数值区间。
example：提供参数的示例值，帮助 API 使用者更直观地理解参数内容。

`@ApiParam` 的属性示例

@ApiParam(value = "用户ID", required = true, example = "12345")
private Long userId;

@ApiParam(value = "状态", allowableValues = "active, inactive", defaultValue = "active")
private String status;

通过这些属性，我们可以更准确地定义接口参数的含义和约束条件，这样不仅让代码更加自解释，也让接口文档更具可读性。

💼 实战演示：如何在项目中使用 `@ApiParam`

接下来，通过一个具体的示例，带大家了解 @ApiParam 的具体用法。假设我们有一个获取用户信息的接口，其中需要传递用户ID和状态两个参数，@ApiParam 可以帮助我们清晰地描述这些参数。

示例代码

@Api(value = "用户接口", tags = "User API")
@RestController
public class UserController {

    @ApiOperation(value = "获取用户信息", notes = "通过用户ID和状态查询用户信息")
    @GetMapping("/user")
    public String getUser(
            @ApiParam(value = "用户ID", required = true, example = "12345") 
            @RequestParam Long userId,
            
            @ApiParam(value = "状态", allowableValues = "active, inactive", defaultValue = "active") 
            @RequestParam String status) {
        return "User Info: " + userId + ", Status: " + status;
    }
}

Swagger UI 效果

在 Swagger UI 中，这个接口会展示为一个可交互的表单，每个参数都带有详细的说明，userId 参数必填，status 参数有默认值“active”。前端同事在调用这个接口时，可以清晰地知道每个参数的用途和约束条件，大大减少了沟通成本。

🚀 扩展：如何结合其他注解优化接口文档

除了 @ApiParam，Swagger 还提供了其他许多注解，它们可以与 @ApiParam 结合使用，进一步优化接口文档。以下是几个常用的组合方式：

1. `@ApiOperation` 和 `@ApiParam` 的组合

@ApiOperation 注解用于描述 API 方法的功能和用途，可以帮助开发者在 Swagger UI 中更详细地描述 API。@ApiParam 用于描述方法的参数，这两个注解结合使用，可以更好地展示 API 的意图。

@ApiOperation(value = "获取用户信息", notes = "查询特定用户的详细信息")
public String getUser(@ApiParam(value = "用户ID", required = true) @RequestParam Long userId) {
    return "User Info";
}

2. `@ApiModel` 和 `@ApiParam` 的组合

如果 API 参数是一个复杂的对象，我们可以使用 @ApiModel 注解为该对象添加描述，再结合 @ApiParam 对参数中的字段进行详细说明。这样既可以整体描述模型，又可以对模型的每个字段进行解释。

@ApiModel(description = "用户详细信息")
public class User {

    @ApiParam(value = "用户名", required = true, example = "JohnDoe")
    private String username;

    @ApiParam(value = "用户年龄", example = "25")
    private Integer age;
}

3. `@ApiResponses` 和 `@ApiParam` 的组合

在接口方法中，@ApiResponses 可以用来描述接口的响应结果，例如成功时返回的数据格式，失败时的错误信息。结合 @ApiParam 描述输入参数，可以让接口文档更加完善和专业。

@ApiOperation(value = "创建用户")
@ApiResponses({
    @ApiResponse(code = 200, message = "用户创建成功"),
    @ApiResponse(code = 400, message = "无效参数"),
    @ApiResponse(code = 500, message = "服务器错误")
})
public String createUser(@ApiParam(value = "用户信息", required = true) @RequestBody User user) {
    return "User Created";
}

以上几种组合方式可以帮助我们更加灵活地创建高质量的 API 文档，使得接口描述更加详细、清晰。

原理剖析

接下来，我们便要对其进行深度地求解，了解其源码并学习其源码所缔造的思想。

剖析 `@ApiParam` 注解原理

@ApiParam 注解是 Swagger 框架中常用的注解之一，它用于为 API 文档中的方法参数提供额外的描述信息，尤其在生成接口文档时，能够帮助开发者更清晰地了解每个参数的含义、类型及是否必填等。@ApiParam 注解通常与 Spring MVC 控制器的参数结合使用。

在如下内容中，我们将深入剖析 @ApiParam 注解的工作原理，如何在 Swagger 中使用该注解，并探讨它的底层实现。

1. `@ApiParam` 注解的作用

@ApiParam 注解的作用是为接口方法的参数提供额外的元数据，比如描述、是否必填、默认值等。这些信息会直接反映在 Swagger API 文档中，从而帮助前端开发人员理解每个 API 接口的参数要求。

通常，@ApiParam 注解用于控制器方法的参数上，来提供与该参数相关的详细信息。例如，可以标记参数的描述、是否为必填项等。

示例代码：

@RestController
public class UserController {

    @ApiOperation(value = "Get user by ID", notes = "This method returns user details by ID")
    @GetMapping("/users/{id}")
    public User getUser(
        @ApiParam(value = "User ID", required = true, example = "12345") @PathVariable Long id) {
        return userService.getUserById(id);
    }
}

在上面的代码中，@ApiParam 注解为 id 参数提供了额外的描述信息，包括：

value：该参数的描述文本，展示在生成的 API 文档中。
required：标记该参数是否为必填项。如果为 true，则在 API 文档中会明确指出该参数是必须的。
example：为该参数提供一个示例值，帮助前端开发者理解该参数的预期值。

2. `@ApiParam` 注解的源码解析

@ApiParam 注解位于 io.swagger.annotations 包中，它的源代码实现非常简洁。下面是 @ApiParam 注解的源码：

/**
 * Swagger注解，用于描述API方法的参数
 */
@Target({ ElementType.PARAMETER, ElementType.FIELD })
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiParam {

    String value() default "";  // 参数描述

    boolean required() default false;  // 是否为必填参数

    String defaultValue() default "";  // 默认值

    String allowableValues() default "";  // 允许的值范围

    String access() default "";  // 访问控制

    String example() default "";  // 示例值
}

核心元素分析：

@Target({ ElementType.PARAMETER, ElementType.FIELD })：注解可以作用于方法的参数和字段。
@Retention(RetentionPolicy.RUNTIME)：注解会在运行时保留，因此可以通过反射读取该注解并用于生成 API 文档。
value：参数的描述信息，简洁明了地说明该参数的意义。
required：是否是必填项，影响生成的 API 文档中是否显示该参数为必填。
defaultValue：指定该参数的默认值，帮助生成 API 文档时提供更全面的信息。
allowableValues：指定允许的取值范围，通常用于枚举类型或特定取值的字段。
access：指定参数的访问权限控制，通常与安全控制相关。
example：指定参数的示例值，方便开发者理解该参数的取值。

3. `@ApiParam` 注解的底层实现

3.1 反射解析

@ApiParam 注解的底层实现主要依赖反射机制。在生成 API 文档时，Swagger 会通过反射扫描控制器方法的参数，查看这些参数上是否存在 @ApiParam 注解。如果存在，Swagger 会根据注解中的信息为参数生成详细的描述。

在生成 Swagger 文档时，Swagger 会遍历每个控制器方法的参数，并解析每个参数上的 @ApiParam 注解：

如果参数上有 @ApiParam 注解，Swagger 会将注解中的描述信息、是否必填、示例值等内容提取出来，并展示在最终生成的 API 文档中。
如果参数上没有 @ApiParam 注解，Swagger 会使用默认的方式显示该参数，通常仅显示参数名和类型。

3.2 Swagger UI 中的展示

当 API 文档生成后，@ApiParam 注解中的信息将直接反映在 Swagger UI 中，帮助前端开发者理解每个接口的参数要求。

在 Swagger UI 中，参数的描述、是否必填、示例值等信息将显示在对应的输入框旁边，确保开发者能够准确地理解每个参数的意义。

3.3 整合到 Springfox Swagger

Springfox Swagger 是 Swagger 在 Spring 项目中的实现，@ApiParam 注解是由 Springfox 处理的。Springfox 会在启动时扫描项目中的所有控制器方法，并根据 @ApiParam 注解生成 API 文档。

以下是 Springfox Swagger 配置类的示例：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
            .paths(PathSelectors.any())
            .build();
    }
}

在 Springfox 配置中，@ApiParam 注解的参数描述信息会被自动提取并用于生成 Swagger 文档，展示在 Swagger UI 中。

4. 小结

@ApiParam 注解 主要用于为 API 方法的参数提供额外的描述信息，帮助生成详细的 API 文档。
它能够指定参数的描述、是否必填、默认值、示例值等信息，从而帮助前端开发者理解接口要求。
在 Swagger 中，@ApiParam 注解的内容会通过反射提取并展示在最终的 API 文档中，通常与 Springfox 等工具一起使用。

通过 @ApiParam 注解的使用，可以大大提高 API 文档的可读性和易用性，使得前后端开发之间的沟通更加清晰。

🎉 总结

简言之，我们详细探讨了 Swagger 中的 @ApiParam 注解，它可以在代码中直接对接口参数进行详细描述，让接口文档更加直观和规范。同时，我们还学习了如何结合其他 Swagger 注解来优化接口文档的展示效果，希望这期的内容能够让同学们有所收获，掌握更多Swagger组件知识点，也期待大家能够分享并开源更多有意思造就我们开发者的组件小工具，节省开发时间，提升开发效率。

📣 关于我

我是bug菌，CSDN | 掘金 | InfoQ | 51CTO | 华为云 | 阿里云 | 腾讯云等社区博客专家，C站博客之星Top30，华为云多年度十佳博主&最具价值贡献奖，掘金多年度人气作者Top40，掘金等各大社区平台签约作者，51CTO年度博主Top12，掘金/InfoQ/51CTO等社区优质创作者；全网粉丝合计 30w+ ；硬核微信公众号「猿圈奇妙屋」，欢迎你的加入！免费白嫖最新BAT互联网公司面试真题、4000G PDF电子书籍、简历模板等海量资料，你想要的我都有，关键是你不来拿。

-End-

@ApiParam详解：用注解玩转API参数，让接口文档更清晰！

前言

📚 目录

正文

🤔 为什么选择 @ApiParam？

🔍 @ApiParam 是什么？作用是什么？

🛠 @ApiParam 的常用属性及详细解析

@ApiParam 的属性示例

💼 实战演示：如何在项目中使用 @ApiParam