swagger常用注解

carl 10/28/2023 javaswagger

# @Api

当使用 Swagger 的 @Api 注解时，可以设置多个属性字段来描述 API 接口的元数据信息。下面是 @Api 注解的属性字段详解，并附带示例：

tags：接口标签，用于对接口进行分类或分组。

@Api(tags = "用户管理")
@RestController
public class UserController {
// ...
}

1
2
3
4
5

value：接口的简要描述。

@Api(value = "用户管理", tags = "用户管理API")
@RestController
public class UserController {
// ...
}

1
2
3
4
5

description：接口的详细描述，支持 Markdown 格式。

@Api(value = "用户管理", description = "提供用户相关的接口操作")
@RestController
public class UserController {
// ...
}

1
2
3
4
5

basePath：接口的基础路径，可以在全局设置中指定。

@Api(basePath = "/api", value = "用户管理")
@RestController
public class UserController {
// ...
}

1
2
3
4
5

consumes：接口支持的请求 Content-Type。

@Api(consumes = MediaType.APPLICATION_JSON_VALUE, value = "用户管理")
@RestController
public class UserController {
// ...
}

1
2
3
4
5

produces：接口返回的响应 Content-Type。

@Api(produces = MediaType.APPLICATION_JSON_VALUE, value = "用户管理")
@RestController
public class UserController {
// ...
}

1
2
3
4
5

protocols：接口支持的协议。

@Api(protocols = "http, https", value = "用户管理")
@RestController
public class UserController {
// ...
}

1
2
3
4
5

# @ApiModel

在 Swagger 中，@ApiModel 注解用于描述模型对象（Model）或 DTO（Data Transfer Object），它通常用在 Java Bean 类上。@ApiModel 注解提供了一些属性和注解，用于详细描述模型对象的属性字段。下面是一些常用的属性和注解：

value：指定模型对象的名称。

@ApiModel(value = "User", description = "用户信息")
public class User {
// ...
}

1
2
3
4

description：描述模型对象的说明。

@ApiModel(value = "User", description = "用户信息，包含姓名和年龄")
public class User {
// ...
}

1
2
3
4

parent：指定模型对象的父类。

@ApiModel(parent = Person.class)
public class User extends Person {
// ...
}

1
2
3
4

discriminator：如果一个类有多个子类，使用 discriminator 属性指定一个字段作为区分标识。

@ApiModel(discriminator = "type")
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type")
@JsonSubTypes({
@JsonSubTypes.Type(value = Dog.class, name = "dog"),
@JsonSubTypes.Type(value = Cat.class, name = "cat")
})
public abstract class Animal {
// ...
}

public class Dog extends Animal {
// ...
}

public class Cat extends Animal {
// ...
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

subTypes：如果一个类是另一个类的子类，可以使用 subTypes 属性指定其子类。

@ApiModel(subTypes = {Dog.class, Cat.class})
public abstract class Animal {
// ...
}

@ApiModel(value = "Dog")
public class Dog extends Animal {
// ...
}

@ApiModel(value = "Cat")
public class Cat extends Animal {
// ...
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

reference：引用其他模型对象，通过 $ref 进行定义。

@ApiModel(value = "User")
public class User {
@ApiModelProperty(value = "用户姓名", example = "Alice")
private String name;

@ApiModelProperty(value = "用户年龄", example = "25")
private int age;

// ...
}

@ApiModel(value = "UserResponse")
public class UserResponse {
@ApiModelProperty(value = "用户信息", reference = "User")
private User user;

// ...
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# @ApiModelProperty

在 Swagger 中，@ApiModelProperty 注释用于描述一个模型属性的元数据信息，可以用来指定属性的名称、类型、描述、默认值、是否必须、可选枚举值等属性。下面是 @ApiModelProperty 注释各属性字段的详解：

value：属性的中文名称或简要描述，例如："用户名"、"用户年龄"；

@ApiModelProperty(value = "用户名")
private String username;

1
2

name：属性的名称，通常与 JavaBean 中的属性名称相同，默认值为空字符串；

@ApiModelProperty(name = "age")
private int userAge;

1
2

dataType：属性的数据类型，可以是基本类型、JavaBean、数组或集合等；

@ApiModelProperty(dataType = "List<String>")
private List<String> hobbies;

1
2

allowableValues：属性可选的枚举值，可以使用字符串数组或枚举类型、或使用逗号分隔的字符串来指定；

@ApiModelProperty(allowableValues = "male, female")
private String gender;

1
2

required：属性是否必须，在 Swagger UI 中的展示时，required 字段为 true 的属性会增加一个红色的星号标识；

@ApiModelProperty(required = true)
private String email;

1
2

example：属性的示例值，可以是任意有效的 JSON 或 XML 字符串；

@ApiModelProperty(example = "john.doe@example.com")
private String email;

1
2

hidden：属性是否隐藏，默认值为 false，如果设置为 true，则 Swagger UI 不会展示该属性；

@ApiModelProperty(hidden = true)
private String secretToken;

1
2

access：属性的访问级别，可以是 "PUBLIC"、"PRIVATE" 或 "INTERNAL" 等；

@ApiModelProperty(access = "INTERNAL")
private String internalId;

1
2

notes：属性的详细说明，可以添加任意的 HTML 标签和样式，支持 Markdown 格式；

@ApiModelProperty(notes = "年龄范围为18到65岁之间")
private int age;

1
2

position：属性在模型中的位置，用于排序和展示，取值为整数，例如 1、2、3 等。

@ApiModelProperty(position = 1)
private String firstName;

@ApiModelProperty(position = 2)
private String lastName;

1
2
3
4
5

# @ApiParam

当使用 Swagger 的 @ApiParam 注解时，可以设置多个属性字段来描述接口参数的元数据信息。下面是 @ApiParam 注解的属性字段详解，并附带示例代码：

name：参数名称。

public void updateUser(@ApiParam(name = "userId") @PathVariable String userId) {
    // ...
}

1
2
3

value：参数的简要描述。

public void updateUser(@ApiParam(value = "用户ID") @PathVariable String userId) {
    // ...
}

1
2
3

required：参数是否必需，默认为 false。

public void updateUser(@ApiParam(name = "userId", required = true) @PathVariable String userId) {
    // ...
}

1
2
3

defaultValue：参数的默认值。

public void updateUser(@ApiParam(name = "username", defaultValue = "guest") @RequestParam String username) {
    // ...
}

1
2
3

allowableValues：参数可选的枚举值。

public void updateUser(@ApiParam(name = "gender", allowableValues = "male, female") @RequestParam String gender) {
    // ...
}

1
2
3

example：参数的示例值。

public void updateUser(@ApiParam(name = "age", example = "25") @RequestParam int age) {
    // ...
}

1
2
3

access：参数的访问级别，可以是 "PUBLIC"、"PRIVATE" 或 "INTERNAL" 等。

public void updateUser(@ApiParam(name = "token", access = "PRIVATE") @RequestParam String token) {
    // ...
}

1
2
3

hidden：参数是否隐藏，默认为 false。

public void updateUser(@ApiParam(name = "password", hidden = true) @RequestParam String password) {
    // ...
}

1
2
3

allowMultiple：是否允许多个值，默认为 false。

public void updateUser(@ApiParam(name = "hobbies", allowMultiple = true) @RequestParam List<String> hobbies) {
    // ...
}

1
2
3

# @ApiImplicitParam

当使用 Swagger 的 @ApiImplicitParam 注解时，可以设置多个属性字段来描述隐式参数的元数据信息。下面是 @ApiImplicitParam 注解的属性字段详解，并附带示例代码：

name：参数名称。

@ApiImplicitParam(name = "userId", value = "用户ID", required = true, dataType = "string", paramType = "path")

value：参数的简要描述。

@ApiImplicitParam(value = "用户ID", required = true, dataType = "string", paramType = "path")

required：参数是否必需，默认为 false。

@ApiImplicitParam(value = "用户ID", required = true, dataType = "string", paramType = "path")

dataType：参数的数据类型。

@ApiImplicitParam(value = "用户年龄", required = true, dataType = "int", paramType = "query")

paramType：参数的类型，可以是 "path"、"query"、"body"、"header" 或 "form"。

@ApiImplicitParam(value = "用户ID", required = true, dataType = "string", paramType = "path")

defaultValue：参数的默认值。

@ApiImplicitParam(value = "用户名", required = true, dataType = "string", paramType = "query", defaultValue = "guest")

allowableValues：参数可选的枚举值。

@ApiImplicitParam(value = "性别", required = true, dataType = "string", paramType = "query", allowableValues = "male,female")

example：参数的示例值。

@ApiImplicitParam(value = "年龄", required = true, dataType = "int", paramType = "query", example = "25")

access：参数的访问级别，可以是 "PUBLIC"、"PRIVATE" 或 "INTERNAL" 等。

@ApiImplicitParam(value = "访问令牌", required = true, dataType = "string", paramType = "header", access = "PRIVATE")

# @ApiImplicitParams

@ApiImplicitParams 内包含多个@ApiImplicitParam

# @ApiResponse

在 Swagger 中，@ApiResponse 注解用于描述 API 方法的响应信息。该注解具有以下属性字段：

code：响应状态码。

@ApiResponse(code = 200, message = "成功")

message：响应描述信息。

@ApiResponse(code = 200, message = "成功")

response：响应的数据类型。

@ApiResponse(code = 200, message = "成功", response = User.class)

reference：引用其他定义的响应模型。

@ApiResponse(code = 200, message = "成功", responseReference = "#/definitions/User")

examples：响应示例。

@ApiResponse(code = 200, message = "成功", examples = @Example(value = {@ExampleProperty(mediaType = "application/json", value = "{\"id\": 1, \"name\": \"John\"}")}))

responseHeaders：响应中的头信息。

@ApiResponse(code = 200, message = "成功", responseHeaders = @ResponseHeader(name = "X-RateLimit-Limit", description = "请求速率限制", response = Integer.class))

responseContainer：如果响应是一个容器（如列表或映射），可以使用该属性指定容器的类型。

@ApiResponse(code = 200, message = "成功", responseContainer = "List")

# @ApiResponses

@ApiResponses 内包含多个 @ApiResponse

# @ApiOperationSupport

排序，作者。不同版本参数不同

@ApiOperationSupport(author ="开发者", order=1 )
@GetMapping("/api/support")
public void supportedMethod() {
    // ...
}

1
2
3
4
5

# @ApiOperation

@ApiOperation 注解的常见属性字段及示例代码：

value：API 方法的简要描述。

@ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户信息")
@GetMapping("/api/users/{id}")
public User getUser(@PathVariable("id") Long id) {
    // ...
}

1
2
3
4
5

notes：API 方法的详细说明。

@ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户信息，包括用户名、邮箱等")
@GetMapping("/api/users/{id}")
public User getUser(@PathVariable("id") Long id) {
    // ...
}

1
2
3
4
5

tags：API 方法所属的标签。

@ApiOperation(value = "获取用户信息", tags = "User")
@GetMapping("/api/users/{id}")
public User getUser(@PathVariable("id") Long id) {
    // ...
}

1
2
3
4
5

response：API 方法的响应类型。

@ApiOperation(value = "获取用户信息", response = User.class)
@GetMapping("/api/users/{id}")
public User getUser(@PathVariable("id") Long id) {
    // ...
}

1
2
3
4
5

responses：多个响应情况的定义。

@ApiOperation(value = "删除用户", responses = {
        @ApiResponse(code = 200, message = "删除成功"),
        @ApiResponse(code = 404, message = "用户不存在")
})
@DeleteMapping("/api/users/{id}")
public void deleteUser(@PathVariable("id") Long id) {
    // ...
}

1
2
3
4
5
6
7
8

# @ApiKeyAuthDefinition

key 需要验证，才能调用接口

# @ApiIgnore

@ApiIgnore 注解用于忽略某个 API 接口，使其不会在生成的 Swagger 文档中显示。

@ApiIgnore("忽略的原因")
@GetMapping("/ignore")
public void ignoredMethod() {
    // ...
}

1
2
3
4
5

# @ApiSort

@ApiSort 注解用于指定 API 接口在 Swagger 文档中的排序位置。

@ApiSort(2)
@GetMapping("/api/sort")
public void sortedMethod2() {
    // ...
}

@ApiSort(1)
@GetMapping("/api/sort")
public void sortedMethod1() {
    // ...
}

1
2
3
4
5
6
7
8
9
10
11

# @ApiSupport

@ApiSupport 注解用于标记某个 API 接口的兼容性支持信息，可以指定支持的版本范围，排序，作者。不同版本参数不同

@ApiSupport(author ="开发者", order=1  since = "2.0", deprecatedSince = "3.0", removedIn = "4.0")
@GetMapping("/api/support")
public void supportedMethod() {
    // ...
}

1
2
3
4
5

carl's blog

Choose mode