Spring Boot作為目前最受歡迎的Java框架之一,擁有快速開發、高度整合、易於測試等優點。在開發過程中,我們經常需要撰寫API文檔,方便前後端協作以及未來專案維護。
然而,手動撰寫API文件是十分耗時且容易出錯的,因此本文將介紹如何利用Spring Boot自帶的註解和一些工具來自動產生API註解和文件。
一、Swagger
Swagger是目前最受歡迎的Java API註解和文件產生工具之一。它可以透過掃描Spring專案中的註釋自動產生API文檔,同時還可以提供互動式的API探索介面。
使用Swagger,你需要在你的Spring Boot專案中加入以下依賴:
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
接著,在Spring Boot的啟動類別中加入註解@EnableSwagger2,如下所示:
@SpringBootApplication @EnableSwagger2 public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }
然後,你可以在你的Controller的方法上加上Swagger提供的註解來產生API文件。
例如,以下是一個簡單的UserController:
@RestController @RequestMapping("/user") public class UserController { @ApiOperation(value = "获取用户列表", notes = "获取所有用户的列表") @GetMapping("/list") public List<User> getUserList() { return userService.getUserList(); } @ApiOperation(value = "创建用户", notes = "根据User对象创建用户") @PostMapping("/") public String postUser(@RequestBody User user) { userService.saveUser(user); return "success"; } @ApiOperation(value = "获取用户详情", notes = "根据id获取用户的详情") @GetMapping("/{id}") public User getUser(@PathVariable Long id) { return userService.getUserById(id); } @ApiOperation(value = "更新用户信息", notes = "根据id更新用户的信息") @PutMapping("/{id}") public String putUser(@PathVariable Long id, @RequestBody User user) { User u = userService.getUserById(id); if (u == null) { return "用户不存在"; } userService.updateUser(user); return "success"; } @ApiOperation(value = "删除用户", notes = "根据id删除用户") @DeleteMapping("/{id}") public String deleteUser(@PathVariable Long id) { User u = userService.getUserById(id); if (u == null) { return "用户不存在"; } userService.deleteUser(id); return "success"; } }
透過加入註解@ApiOperation和其他相關的註解,Swagger將會自動產生API文檔,並提供互動式的API探索介面。
你可以透過造訪http://localhost:8080/swagger-ui.html來檢視你的API文件。
二、Spring REST Docs
Spring REST Docs是另一個Java API註解和文件產生工具,它允許你使用AsciiDoc、Markdown或HTML格式來編寫API文件。
使用Spring REST Docs,你需要在你的Spring Boot專案中加入以下依賴:
<dependency> <groupId>org.springframework.restdocs</groupId> <artifactId>spring-restdocs-mockmvc</artifactId> <version>2.0.2.RELEASE</version> </dependency>
接著,在你的測試類別中加入註解@WebMvcTest,如下所示:
@RunWith(SpringRunner.class) @WebMvcTest(UserController.class) public class UserControllerTests { @Autowired private MockMvc mockMvc; @Test public void getUserList() throws Exception { this.mockMvc.perform(get("/user/list")) .andExpect(status().isOk()) .andDo(document("getUserList", responseFields( fieldWithPath("[].id").description("用户ID"), fieldWithPath("[].name").description("用户名"), fieldWithPath("[].age").description("用户年龄") ))); } @Test public void postUser() throws Exception { User user = new User(); user.setName("Tom"); user.setAge(20); ObjectMapper mapper = new ObjectMapper(); String userJson = mapper.writeValueAsString(user); this.mockMvc.perform(post("/user/") .contentType(MediaType.APPLICATION_JSON) .content(userJson)) .andExpect(status().isOk()) .andDo(document("postUser", requestFields( fieldWithPath("name").description("用户名"), fieldWithPath("age").description("用户年龄") ))); } @Test public void getUser() throws Exception { this.mockMvc.perform(get("/user/{id}", 1)) .andExpect(status().isOk()) .andDo(document("getUser", pathParameters( parameterWithName("id").description("用户ID") ), responseFields( fieldWithPath("id").description("用户ID"), fieldWithPath("name").description("用户名"), fieldWithPath("age").description("用户年龄") ))); } @Test public void putUser() throws Exception { User user = new User(); user.setName("Tom"); user.setAge(20); ObjectMapper mapper = new ObjectMapper(); String userJson = mapper.writeValueAsString(user); this.mockMvc.perform(put("/user/{id}", 1) .contentType(MediaType.APPLICATION_JSON) .content(userJson)) .andExpect(status().isOk()) .andDo(document("putUser", pathParameters( parameterWithName("id").description("用户ID") ), requestFields( fieldWithPath("name").description("用户名"), fieldWithPath("age").description("用户年龄") ))); } @Test public void deleteUser() throws Exception { this.mockMvc.perform(delete("/user/{id}", 1)) .andExpect(status().isOk()) .andDo(document("deleteUser", pathParameters( parameterWithName("id").description("用户ID") ))); } }
透過加入對應的註解和欄位描述,Spring REST Docs會自動產生API文檔,並將其儲存在/target/generated-snippets目錄中,你可以將其轉換為最終的文檔格式。
三、總結
本文介紹了兩種實作基於Spring Boot的API註解和文件產生的方法。 Swagger提供了一種方便、易用的方式,生成的文件也比較直觀易懂,適合小型專案或快速開發。而Spring REST Docs則提供了更靈活、可自訂的方式,可以適用於更複雜的專案和對API文件品質要求較高的場景。
無論你選擇了哪種方式,API文件的正確、規範和清晰是必不可少的,它不僅方便前後端協作,也有助於你的專案長期維護。
以上是如何實現基於Spring Boot的API註解和文件生成的詳細內容。更多資訊請關注PHP中文網其他相關文章!