Spring Boot作為目前最受歡迎的Java框架之一，擁有快速開發(fā)、高度整合、易於測(cè)試等優(yōu)點(diǎn)。在開發(fā)過(guò)程中，我們經(jīng)常需要撰寫API文檔，方便前後端協(xié)作以及未來(lái)專案維護(hù)。

然而，手動(dòng)撰寫API文件是十分耗時(shí)且容易出錯(cuò)的，因此本文將介紹如何利用Spring Boot自帶的註解和一些工具來(lái)自動(dòng)產(chǎn)生API註解和文件。

一、Swagger

Swagger是目前最受歡迎的Java API註解和文件產(chǎn)生工具之一。它可以透過(guò)掃描Spring專案中的註釋自動(dòng)產(chǎn)生API文檔，同時(shí)還可以提供互動(dòng)式的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的啟動(dòng)類別中加入註解@EnableSwagger2，如下所示：

@SpringBootApplication
@EnableSwagger2
public class DemoApplication {
   public static void main(String[] args) {
      SpringApplication.run(DemoApplication.class, args);
   }
}

然後，你可以在你的Controller的方法上加上Swagger提供的註解來(lái)產(chǎn)生API文件。

例如，以下是一個(gè)簡(jiǎn)單的UserController：

@RestController
@RequestMapping("/user")
public class UserController {
  
   @ApiOperation(value = "獲取用戶列表", notes = "獲取所有用戶的列表")
   @GetMapping("/list")
   public List<User> getUserList() {
      return userService.getUserList();
   }
  
   @ApiOperation(value = "創(chuàng)建用戶", notes = "根據(jù)User對(duì)象創(chuàng)建用戶")
   @PostMapping("/")
   public String postUser(@RequestBody User user) {
      userService.saveUser(user);
      return "success";
   }
  
   @ApiOperation(value = "獲取用戶詳情", notes = "根據(jù)id獲取用戶的詳情")
   @GetMapping("/{id}")
   public User getUser(@PathVariable Long id) {
      return userService.getUserById(id);
   }
  
   @ApiOperation(value = "更新用戶信息", notes = "根據(jù)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 = "根據(jù)id刪除用戶")
   @DeleteMapping("/{id}")
   public String deleteUser(@PathVariable Long id) {
      User u = userService.getUserById(id);
      if (u == null) {
          return "用戶不存在";
      }
      userService.deleteUser(id);
      return "success";
   }
}

透過(guò)加入註解@ApiOperation和其他相關(guān)的註解，Swagger將會(huì)自動(dòng)產(chǎn)生API文檔，並提供互動(dòng)式的API探索介面。

你可以透過(guò)造訪http://localhost:8080/swagger-ui.html來(lái)檢視你的API文件。

二、Spring REST Docs

Spring REST Docs是另一個(gè)Java API註解和文件產(chǎn)生工具，它允許你使用AsciiDoc、Markdown或HTML格式來(lái)編寫API文件。

使用Spring REST Docs，你需要在你的Spring Boot專案中加入以下依賴：

<dependency>
   <groupId>org.springframework.restdocs</groupId>
   <artifactId>spring-restdocs-mockmvc</artifactId>
   <version>2.0.2.RELEASE</version>
</dependency>

接著，在你的測(cè)試類別中加入註解@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")
             )));
   }
}

透過(guò)加入對(duì)應(yīng)的註解和欄位描述，Spring REST Docs會(huì)自動(dòng)產(chǎn)生API文檔，並將其儲(chǔ)存在/target/generated-snippets目錄中，你可以將其轉(zhuǎn)換為最終的文檔格式。

三、總結(jié)

本文介紹了兩種實(shí)作基於Spring Boot的API註解和文件產(chǎn)生的方法。 Swagger提供了一種方便、易用的方式，生成的文件也比較直觀易懂，適合小型專案或快速開發(fā)。而Spring REST Docs則提供了更靈活、可自訂的方式，可以適用於更複雜的專案和對(duì)API文件品質(zhì)要求較高的場(chǎng)景。

無(wú)論你選擇了哪種方式，API文件的正確、規(guī)範(fàn)和清晰是必不可少的，它不僅方便前後端協(xié)作，也有助於你的專案長(zhǎng)期維護(hù)。

以上是如何實(shí)現(xiàn)基於Spring Boot的API註解和文件生成的詳細(xì)內(nèi)容。更多資訊請(qǐng)關(guān)注PHP中文網(wǎng)其他相關(guān)文章！