@apiparam参数详解

一、@apiparam参数说明

@apiparam是Swagger中用来描述API操作的参数对象的关键字，它是Swagger参数中的一种。它的作用是：定义HTTP请求时所使用的参数，以及在API操作中所使用的输入参数和输出参数

我们经常在编写API接口文档时会用到@apiparam关键字，一般来说，使用@apiparam可以提供很多对API的参数操作描述信息，例如参数名称、参数位置、参数类型等等。

在Swagger中，定义一个参数时，需要使用@apiparam关键字。如下所示：

/**
 * 获取用户信息
 * 
 * @param {string} userId 用户ID
 * @param {string} token 用户Token
 * @param {string} [gender] 性别
 * @return {Object} 用户信息
 */

在上面的代码中，@apiparam关键字的使用非常简单，它后面的内容描述了在获取用户信息API操作中用到的参数以及参数的类型和说明。其中，参数名称是必填项，其他参数则可选。我们来详细看一下每个参数的含义。

二、apidmini6参数

apidmini6是Swagger中一些常用的参数选项，在@apiparam中也可以用来进行参数定义

1、in参数

in参数是指参数的位置，有以下几种选择：

path：参数位于URL路径中
query：参数位于查询参数中
header：参数位于请求头信息中
cookie：参数位于cookie中

例如：

/**
 * @param {number} petId 在URL路径中的宠物ID
 */

2、required参数

required参数指定参数是否可以为空。它的值可以是true或者false。

/**
 * @param {number} petId 在URL路径中的宠物ID
 * @param {string} [status] 宠物状态，默认为"available"
 */

上述代码中，petId参数是必须的，而status不是必须的，因为status的required参数值为false。

3、description参数

description参数用于描述参数的含义。

/**
 * @param {number} petId 在URL路径中的宠物ID
 * @param {string} [status] 宠物状态，默认为"available"
 * @param {string} [name] 宠物名字
 * @param {string} [tag] 宠物标签
 */

上述代码中，每个参数都使用了description参数进行了参数描述。

4、example参数

example参数用于提供值的示例，以便用户了解如何填写参数值。

/**
 * @param {number} petId 在URL路径中的宠物ID。例如：54321
 * @param {string} [status] 宠物状态，默认为"available"。例如："sold"
 * @param {string} [name] 宠物名字。例如："狗狗"
 * @param {string} [tag] 宠物标签。例如："蓝色"
 */

上述代码中，每个参数都使用了example参数提供了示例值，使用户能够更好的了解如何填写参数值。

5、format参数

format参数通过提供数据的格式，来提供有关传递数据的附加信息。

/**
 * @param {string} username 用户名
 * @param {string} password 密码
 */

在上述代码中，格式是没有说明的。例如，我们可以将格式指定为”password”：

/**
 * @param {string} username 用户名
 * @param {string} password 密码
 *     @format password
 */

三、其他参数

除了apidmini6参数选项之外，Swagger还有其他一些常见的参数选项，可以在@apiparam中使用。

1、type参数

type参数指定参数的类型。它的类型可以是字符串、数字、整数、布尔值、数组等。

/**
 * @param {string} username 用户名
 * @param {string} password 密码
 * @param {number} age 年龄
 * @param {boolean} isVip 是否是VIP用户
 * @param {array} tags 标签
 */

2、minimum和maximum参数

minimum和maximum参数用于指定参数的最小值和最大值。

/**
 * @param {number} age 年龄
 *     @minimum 18
 *     @maximum 100
 */

在上述代码中，用户的age参数的值必须在18到100之间。

3、pattern参数

pattern参数通过正则表达式匹配值。例如，下面例子中，email参数必须是有效的电子邮件地址：

/**
 * @param {string} email 电子邮件地址
 *     @pattern ^[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$
 */

4、enum参数

enum参数用于指定参数值的范围。例如：

/**
 * @param {string} status 订单状态
 *     @enum {string} placed - 订单已经下单
 *           {string} approved - 订单已经批准
 *           {string} delivered - 订单已经交付
 */

在上述代码中，status参数的值只能为三种枚举类型之一，包括placed、approved和delivered。

5、items参数

items参数用于指定数组或对象类型的元素的类型。例如，在下面的代码中，pets参数是一个包含pet对象的数组：

/**
 * @param {array} pets 包含pet对象的数组
 *     @items {object} pet
 *           {string} name 名称
 *           {string} species 种类
 */

在上述代码中，description参数中的items用来指定数组中元素的类型。

总结

本文介绍了@apiparam关键字以及与之相关的apidmini6参数选项和其他参数选项，每个参数选项都有详细的阐述和示例，希望本文对大家编写Swagger文档有所帮助。

原创文章，作者：小蓝，如若转载，请注明出处：https://www.506064.com/n/306226.html