Cara melaksanakan anotasi API dan penjanaan dokumen berdasarkan Spring Boot

Sebagai salah satu rangka kerja Java yang paling popular pada masa ini, Spring Boot mempunyai kelebihan pembangunan pesat, integrasi tinggi dan ujian mudah. Semasa proses pembangunan, kami selalunya perlu menulis dokumen API untuk memudahkan kerjasama hadapan dan belakang serta penyelenggaraan projek pada masa hadapan.

Walau bagaimanapun, menulis dokumentasi API secara manual sangat memakan masa dan terdedah kepada ralat, jadi artikel ini akan memperkenalkan cara menggunakan anotasi Spring Boot sendiri dan beberapa alatan untuk menjana ulasan dan dokumentasi API secara automatik.

1. Swagger

Swagger ialah salah satu alat penjanaan anotasi dan dokumentasi Java API yang paling popular. Ia boleh menjana dokumentasi API secara automatik dengan mengimbas anotasi dalam projek Spring, dan juga boleh menyediakan antara muka penerokaan API interaktif.

Untuk menggunakan Swagger, anda perlu menambah kebergantungan berikut pada projek Spring Boot anda:

<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>

Kemudian, tambahkan anotasi @EnableSwagger2 dalam kelas permulaan Spring Boot, seperti yang ditunjukkan di bawah:

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

Kemudian, anda boleh menambah anotasi yang disediakan oleh Swagger pada kaedah Pengawal anda untuk menjana dokumentasi API.

Sebagai contoh, yang berikut ialah UserController yang mudah:

@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";
   }
}

Dengan menambahkan anotasi @ApiOperation dan anotasi lain yang berkaitan, Swagger akan menjana dokumentasi API secara automatik dan menyediakan antara muka penerokaan API interaktif.

Anda boleh melihat dokumentasi API anda dengan melawati http://localhost:8080/swagger-ui.html.

2. Spring REST Docs

Spring REST Docs ialah alat penjanaan anotasi dan dokumentasi API Java yang membolehkan anda menulis dokumentasi API menggunakan format AsciiDoc, Markdown atau HTML.

Menggunakan Spring REST Docs, anda perlu menambah kebergantungan berikut pada projek Spring Boot anda:

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

Seterusnya, tambah anotasi @WebMvcTest ke kelas ujian anda seperti berikut:

@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")
             )));
   }
}

Dengan menambahkan anotasi dan huraian medan yang sepadan, Spring REST Docs akan menjana dokumentasi API secara automatik dan menyimpannya dalam direktori /target/generated-snippets, yang boleh anda tukar kepada format dokumentasi akhir.

3. Ringkasan

Artikel ini memperkenalkan dua kaedah untuk melaksanakan anotasi API dan penjanaan dokumen berdasarkan Spring Boot. Swagger menyediakan kaedah yang mudah dan mudah digunakan, dan dokumen yang dihasilkan adalah agak intuitif dan mudah difahami, menjadikannya sesuai untuk projek kecil atau pembangunan pesat. Spring REST Docs menyediakan pendekatan yang lebih fleksibel dan boleh disesuaikan, yang boleh digunakan pada projek dan senario yang lebih kompleks yang memerlukan dokumentasi API berkualiti tinggi.

Tidak kira kaedah yang anda pilih, dokumentasi API adalah penting, diseragamkan dan jelas Ia bukan sahaja memudahkan kerjasama bahagian hadapan dan belakang, tetapi juga membantu penyelenggaraan jangka panjang projek anda .

Atas ialah kandungan terperinci Cara melaksanakan anotasi API dan penjanaan dokumen berdasarkan Spring Boot. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!