设置 Swagger 文档中的示例和描述

2023-09-09

教程

1、概览

在本教程中，我们将演示如何使用 Swagger 注解使我们的文档更具描述性。我们会学习如何为 API 的不同部分（如方法、参数、响应等）添加描述，以及如何添加请求/响应示例。

2、项目设置

我们将创建一个简单的 Product API，提供创建和获取 product 的方法。

要从头开始创建 REST API，我们可以按照 Spring 文档中的教程使用 Spring Boot 创建 RESTful Web 服务。

下一步是为项目设置依赖和配置。我们可以按照本文中的步骤使用 Spring REST API 设置 Swagger 2

3、创建 API

创建 Product API 并检查生成的文档。

3.1、Model

定义 Product 类：

public class Product implements Serializable {
    private long id;
    private String name;
    private String price;

    // 省略 get/set 构造函数
}

3.2、Controller

定义两个 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 上查看文档：

Swagger 文档

我们可以进一步扩展 controller 方法，使其文档更加详细。

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 来更改不同响应状态码的消息。

例如，假设找不到 product，在这种情况下，我们的 API 会返回 HTTP 404 状态。如果我们不添加自定义消息，原始消息 “Not found” 可能很难理解。调用者可能会将其理解为 URL 有误。改为 “The product was not found” 的描述就会更清晰。

@Parameter 定义了方法参数的属性。它可以与 path、query、header 和 form 参数一起使用。我们为 “id” 参数添加了名称、描述和示例。如果我们不添加自定义信息，文档将只显示接收参数的名称和类型，如第一张图片所示。

加上注解配置后，让我们来看看文档有什么变化：

swagger API 详情

此时，我们可以看到名称 “Get a product id” 和 API 路径 /products/{id} 并列。我们还可以看到下面的说明。此外，在 Parameters 部分，我们还有关于 id 字段的描述和示例。最后，在 Responses 部分，我们可以看到 200 和 404 状态码的描述发生了变化。

4.2、为 Model 添加说明和示例

我们可以对 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 model 的文档：

Swagger Model

如果我们将其与原始文档进行比较，就会发现新的文档包含示例、说明和红色星号（*），以标识参数是必需的。

通过为 model 添加示例，我们可以在每个使用 model 作为输入或输出的方法中自动创建示例响应。例如，从与 getProduct() 方法相对应的文档中，我们可以看到响应包含了一个示例，其中的值与我们在 model 中提供的值相同。

在文档中添加示例非常重要，因为这样可以使值格式更加精确。如果我们的 model 包含日期、时间或价格等字段，就需要精确的值的格式。事先定义好格式可以使 API 提供方和 API 客户端的开发过程更加有效。

5、总结

在本文中，我们探讨了提高 API 文档可读性的不同方法。我们学习了如何使用 @Parameter、@Operation、@ApiResponses、@ApiResponse 和 @Schema 注解来为来为 swagger 文档中的方法、参数、错误信息和 model 生成更详细的描述。

参考：https://www.baeldung.com/swagger-set-example-description