swagger3.0常用注解

### 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("[email protected]"))); } } ``` #### 控制器级别注解 此类别的注解用来标记控制器层面上的内容，以便让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(); } // ...其他业务逻辑... } ``` 通过以上方式，不仅可以使开发人员更加直观地理解各个接口的作用范围，同时也方便了前端工程师快速掌握后端提供的功能特性。