###
Swagger 3.0 中
常用注解及其用法
在
Swagger 3.0中，为了更好地描述API并使其更易于理解和使用，引入了一系列
注解来帮助开发者定义和展示API的功能。以下是几个
常用的
注解以及它们的应用场景。
#### @EnableOpenApi
注解
此
注解用于启用Spring应用程序中的OpenAPI支持，在应用的主
类或者配置
类上添加该
注解可以开启对
Swagger的支持[^3]。
```java
@SpringBootApplication
@EnableOpenApi
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
```
#### API 文档级别的元数据
注解
这些
注解主要用于提供关于整个API的信息，比如标题、版本号等基本信息。
- **@OpenAPIDefinition**: 定义全局性的API信息，如服务名称和服务条款链接等。
- **@Info**: 提供有关API的具体细节，例如标题、描述、版本等。
- **@Contact**: 描述联系人的信息，可用于指明谁负责维护这个API。
- **@License**: 表示API使用的许可证
类型及URL。
下面是
一个组合上述多个
注解的例子：
```java
@Configuration
public class OpenApiConfig {
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info().title("Sample API")
.description("This is a sample server Petstore server.")
.version("1.0")
.license(new License().name("Apache 2.0").url("http://springdoc.org"))
.contact(new Contact().email("support@example.com")));
}
}
```
#### 控制器级别
注解
此
类别的
注解用来标记控制器层面上的内容，以便让
Swagger知道哪些
方法应该被记录下来作为公开可用的服务端点。
- **@Operation**: 对单个操作进行
说明，可指定摘要、描述等内容。
- **@Parameter**: 添加参数的相关信息，包括位置（查询字符串还是路径变量）、是否必填等属性。
- **@ApiResponse**: 设置响应的状态码及相关消息体结构。
- **@RequestBody**: 当请求体中有复杂对象时使用，能够清晰表达输入的数据格式。
这里给出一段带有`@RestController`和相关
注解的实际代码片段：
```java
@RestController
@RequestMapping("/pets")
public class PetController {
private final PetService petService;
@Autowired
public PetController(PetService petService){
this.petService = petService;
}
/**
* 获取宠物列表.
*/
@GetMapping("")
@Operation(summary="获取所有宠物", description="返回当前系统中存在的全部宠物实体")
@ApiResponse(responseCode = "200", content = {@Content(mediaType = "application/json",
schema=@Schema(implementation=Pet[].class))})
ResponseEntity<List<Pet>> getPets(){
List<Pet> pets = petService.getAllPets();
return new ResponseEntity<>(pets, HttpStatus.OK);
}
/**
* 创建新宠物.
*/
@PostMapping("")
@Operation(summary="创建新的宠物条目", description="向数据库插入一条新的宠物记录")
@ApiResponse(responseCode = "201", description = "成功创建了
一个新的宠物实例")
ResponseEntity<Void> addNewPet(@Valid @RequestBody CreatePetRequest request){
Long id = petService.create(request.getName(),request.getCategory());
URI location = ServletUriComponentsBuilder.fromCurrentContextPath().path("/{id}")
.buildAndExpand(id).toUri();
return ResponseEntity.created(location).build();
}
// ...其他业务逻辑...
}
```
通过以上方式，不仅可以使开发人员更加直观地理解各个接口的作用范围，同时也方便了前端工程师快速掌握后端提供的功能特性。
本文详细介绍了Swagger常用的注解，帮助开发者更好地理解和使用Swagger，提升API文档的生成效率和质量。
扫一扫
703
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
