Spring Boot集成Swagger API文檔：傻瓜式零基礎教程

Springfox Swagger 是一個用于構建基于 Spring Boot 的?RESTful API?文檔的開源工具。它通過使用注解來描述 API 端點，自動生成易于閱讀和理解的 API 文檔。Springfox 通過在運行時檢查應用程序，基于 Spring 配置、類結構和各種編譯時 Java 注釋來推斷 API 語義。

在 Java 項目中使用 Springfox 有以下好處：

自動生成 API 文檔：Springfox 可以幫助我們自動生成描述 API 的 JSON 文件(Swagger 2.0規范)，這使得 API 文檔的編寫變得非常容易和高效。
可視化 API 文檔：Springfox 還提供了一個?Swagger UI，可以將 API 規范以交互式文檔的形式展示出來，使得開發者和用戶可以更加直觀地理解和使用 API。
減少重復勞動：使用 Springfox 可以減少開發人員編寫和維護 API 文檔的工作量，從而提高開發效率。

需要注意的是，Springfox 3.x 版本已經移除了對 Guava 和其他第三方庫的依賴，因此如果之前使用了 Guava predicates/functions，需要將其轉換為 Java 8 函數接口。同時，在 SpringBoot 項目中整合 Springfox 通常需要用到兩個依賴：springfox-swagger2 和 springfox-swagger-ui。

快速上手 springfox

安裝依賴

如果是新項目，添加以下為 maven 依賴

<dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version>
</dependency>

Gradle 則添加這個

  implementation "io.springfox:springfox-boot-starter:<version>"

Swagger 配置入口


@SpringBootApplication
@EnableSwagger2 //支持 swagger 2.0 spec
@EnableOpenApi //支持 open api 3.0.3 spec
public class Application {public static void main(String[] args) {ApplicationContext ctx = SpringApplication.run(Application.class, args);}@Beanpublic PetController petController() {return new PetController();}

引入 swagger UI

<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>3.0.0</version>
</dependency>

設置 Swagger UI 靜態資源目錄


@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}

試試修改 Controller

@RestController
public class CustomController {@RequestMapping(value = "/custom", method = RequestMethod.POST)public String custom() {return "custom";}
}

Entity 校驗

@Entity
public class User {//...@NotNull(message = "First Name cannot be null")private String firstName;@Min(value = 15, message = "Age should not be less than 15")@Max(value = 65, message = "Age should not be greater than 65")private int age;
}

瀏覽器驗證 Json 文件

訪問?http://localhost:8080/api/v2/api-docs，如果配置沒問題的話，就可以拿到?swagger spec 文件。

訪問?http://localhost:8080/swagger-ui/?看是否能夠看到 Swagger UI。

Swagger UI

示例代碼

以下是一個基于 Springfox Swagger 的代碼示例：

@RestController
@RequestMapping("/api/v1/users")
@Api(tags = "User Management", description = "Operations for managing users")
public class UserController {@Autowiredprivate UserService userService;@GetMapping("/{id}")@ApiOperation(value = "Get user by ID", notes = "Get the user information by user ID")@ApiResponses(value = {@ApiResponse(code = 200, message = "Successfully retrieved user information"),@ApiResponse(code = 404, message = "User not found"),@ApiResponse(code = 500, message = "Internal server error")})public ResponseEntity<User> getUserById(@PathVariable("id") Long id) {User user = userService.getUserById(id);if (user == null) {return ResponseEntity.notFound().build();}return ResponseEntity.ok(user);}@PostMapping@ApiOperation(value = "Create user", notes = "Create a new user with the given user information")@ApiResponses(value = {@ApiResponse(code = 201, message = "Successfully created user"),@ApiResponse(code = 400, message = "Invalid request body"),@ApiResponse(code = 500, message = "Internal server error")})public ResponseEntity<User> createUser(@RequestBody @Valid User user) {User newUser = userService.createUser(user);return ResponseEntity.created(URI.create("/api/v1/users/" + newUser.getId())).body(newUser);}@PutMapping("/{id}")@ApiOperation(value = "Update user", notes = "Update an existing user with the given user information")@ApiResponses(value = {@ApiResponse(code = 200, message = "Successfully updated user"),@ApiResponse(code = 400, message = "Invalid request body"),@ApiResponse(code = 404, message = "User not found"),@ApiResponse(code = 500, message = "Internal server error")})public ResponseEntity<User> updateUser(@PathVariable("id") Long id, @RequestBody @Valid User user) {User updatedUser = userService.updateUser(id, user);if (updatedUser == null) {return ResponseEntity.notFound().build();}return ResponseEntity.ok(updatedUser);}@DeleteMapping("/{id}")@ApiOperation(value = "Delete user", notes = "Delete an existing user by user ID")@ApiResponses(value = {@ApiResponse(code = 204, message = "Successfully deleted user"),@ApiResponse(code = 404, message = "User not found"),@ApiResponse(code = 500, message = "Internal server error")})public ResponseEntity<Void> deleteUser(@PathVariable("id") Long id) {boolean deleted = userService.deleteUser(id);if (deleted) {return ResponseEntity.noContent().build();}return ResponseEntity.notFound().build();}
}

在上述示例代碼中，使用了多個注解來描述 API 端點，例如：

@RestController：標識該類為一個 RESTful API 的控制器。
@RequestMapping：標識該控制器中所有 API 端點的基本路徑。
@GetMapping、@PostMapping、@PutMapping、@DeleteMapping：分別表示 GET、POST、PUT 和 DELETE 請求的 API 端點。
@Api：用于為該控制器中所有 API 端點添加一個描述性的標簽和說明。
@ApiOperation：用于為單個 API 端點添加一個描述性的標簽和說明。
@ApiResponses：用于為單個 API 端點添加一個或多個可能的響應消息。

除了上述注解之外，示例代碼還包括了其他的注解，如?@PathVariable、@RequestBody、@Valid?等。這些注解用于描述 API 端點的輸入參數和返回結果。

在添加了注解之后，開發人員可以使用 Springfox Swagger 來自動生成 API 文檔。例如，通過訪問?/v2/api-docs?端點，可以獲取生成的 Swagger JSON 文件。另外，通過訪問?/swagger-ui.html?端點，可以獲取一個可視化的 Swagger UI 界面，用于查看和測試 API 端點。

好用的 API 開發者工具

Springfox Swagger 是一個功能強大的工具，但也有一些缺點：

學習成本高：使用 Springfox Swagger 需要掌握大量的注解和配置，這需要一定的學習成本。特別是對于初學者來說，可能需要花費更多的時間來了解和掌握 Springfox Swagger 的使用方法。
文檔生成的細節有限制：雖然 Springfox Swagger 能夠自動生成 API 文檔，但是文檔生成的細節受到限制，無法自動識別一些細節，例如 API 端點間的依賴關系、數據模型的細節等。這些需要開發者手動進行配置。
API 文檔維護需謹慎：API 文檔的內容需要和代碼一致，如果開發者沒有及時更新 API 文檔，就可能導致文檔和實際代碼不一致，增加維護的難度。
不支持自定義文檔：盡管 Springfox Swagger 提供了多種自定義主題和樣式的選項，但仍存在一些自定義文檔的需求無法滿足。例如，開發者可能需要根據特定的需求，生成自己定制的 API 文檔，而這是不容易實現的。
增加應用程序復雜度：在將 Springfox Swagger 集成到應用程序中時，需要增加一些配置和注解，這可能會增加應用程序的復雜度。這也可能會增加代碼的維護成本，特別是在大型項目中。

對于開發者，我們更推薦一體化 API 工具?Apifox：Apifox 是一個接口管理、開發、測試全流程集成工具，可以通過一套系統、一份數據解決多個系統之間的 API 數據同步問題。Apifox 提供的功能包括接口文檔管理、接口調試、數據 Mock、接口測試等，可以幫助團隊提高效率，降低溝通成本。?此外，Apifox 還有許多創新功能，如接口支持用例管理、接口支持分組管理、多人協作編輯等，都可以提高團隊的開發效率。

立即體驗 Apifox

一體化 API 工具 Apifox