概述
本教程将展示如何使用Swagger注解来使我们的文档更具描述性。首先，我们将学习如何为API的不同部分添加描述，如方法、参数和错误代码。然后，我们将探讨如何添加请求/响应示例。
项目设置
我们将创建一个简单的Products API，提供创建和获取产品的方法。
要从头开始创建REST API，可以参考Spring Docs的教程：使用Spring Boot构建RESTful Web服务
接下来，我们将设置项目的依赖项和配置。可以按照这篇文章中的步骤进行操作：与Spring REST API集成Swagger 2
创建API
现在，让我们创建Products API并查看生成的文档。
3.1. 模型
定义我们的Product类：
public class Product implements Serializable {
private long id;
private String name;
private String price;
// constructor and getter/setters
}
3.2. 控制器
定义两个API方法：
@RestController
@Tag(name = "Products API")
public class ProductController {
@PostMapping("/products")
public ResponseEntity<Void> createProduct(@RequestBody Product product) {
//creation logic
return new ResponseEntity<>(HttpStatus.CREATED);
}
@GetMapping("/products/{id}")
public ResponseEntity<Product> getProduct(@PathVariable Long id) {
//retrieval logic
return ResponseEntity.ok(new Product(1, "Product 1", "$21.99"));
}
}
运行项目后，库将读取所有公开的路径，并创建相应的文档。
在默认URL http://localhost:8080/swagger-ui/index.html 查看文档：
我们可以进一步扩展控制器方法以查看各自的详细文档。接下来，我们将深入研究它们。
4. 提高文档描述性
现在，我们将通过向方法的不同部分添加描述，使我们的文档更加详尽。
4.1. 在方法和参数上添加描述
让我们看看几种使方法更具描述性的方式。我们将为方法、参数和响应代码添加描述。我们先从getProduct()方法开始：
@Operation(summary = "Get a product by id", description = "Returns a product as per the id")
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "Successfully retrieved"),
@ApiResponse(responseCode = "404", description = "Not found - The product was not found")
})
@GetMapping("/products/{id}")
public ResponseEntity<Product> getProduct(@PathVariable("id") @Parameter(name = "id", description = "Product id", example = "1") Long id) {
//retrieval logic
return ResponseEntity.ok(new Product(1, "Product 1", "$21.99"));
}
@Operation 定义了API方法的属性。 我们使用value属性添加了一个操作名称，使用notes属性添加了一个描述。
@ApiResponses 用于覆盖响应代码的默认消息。 对于每个我们想要更改的响应消息，都需要添加一个@ApiResponse对象。
例如，如果产品未找到，而我们的API在这种情况下返回HTTP 404状态。如果我们不添加自定义消息，原始消息“Not found”可能难以理解，调用者可能会认为URL有误。然而，添加一个描述“产品未找到”会使情况更清晰。
@Parameter 定义了方法参数的属性。 它可以与路径、查询、头和表单参数一起使用。我们在“id”参数上添加了一个名称、值（描述）和示例。如果没有自定义设置，库只会获取参数的名称和类型，如第一张图所示。
让我们看看这对文档有何影响：
在这里，我们可以看到路径“获取产品ID”旁边有API路径/products/{id}。下面就是描述。此外，在参数部分，我们为字段“id”提供了描述和示例。在响应部分，我们可以看到对于200和404代码的错误描述已更改。
4.2. 在模型上添加描述和示例
我们可以在createProduct()方法中做出类似的改进。由于该方法接受一个Product对象，所以在Product类本身中提供描述和示例更为合适。
让我们对Product类进行一些更改以实现这一点：
@Schema(name = "Product ID", example = "1", required = true)
private Long id;
@Schema(name = "Product name", example = "Product 1", required = false)
private String name;
@Schema(name = "Product price", example = "$100.00", required = true)
private String price;
@Schema 注解用于定义字段的属性。 我们在每个字段上使用此注解设置了其name、example和required属性。
重启应用，再次查看Product模型的文档：
如果我们比较这两张图，会发现新图包含了示例、描述以及红色星号(*)来标识必填参数。
通过为模型添加示例，我们可以自动在使用模型作为输入或输出的所有方法中创建示例响应。例如，对应于getProduct()方法的图片中，我们可以看到响应包含包含我们在模型中提供的相同值的示例。
为文档添加示例非常重要，因为它使值格式更加精确。如果我们的模型包含日期、时间或价格等字段，精确的值格式是必要的。提前定义格式对于API提供者和API客户端的开发过程都更有效。
5. 结论
在这篇文章中，我们探索了提高API文档可读性的不同方法。我们学会了如何使用@Parameter、@Operation、@ApiResponses、@ApiResponse和@Schema注解来文档化方法、参数、错误消息和模型。
如往常一样，这些示例的代码可在GitHub上找到：GitHub。