Comment implémenter l'annotation API et la génération de documents basés sur Spring Boot

En tant que l'un des frameworks Java les plus populaires à l'heure actuelle, Spring Boot présente les avantages d'un développement rapide, d'une intégration élevée et de tests faciles. Au cours du processus de développement, nous devons souvent rédiger des documents API pour faciliter la collaboration front-end et back-end et la maintenance future des projets.

Cependant, l'écriture manuelle de la documentation de l'API prend beaucoup de temps et est sujette aux erreurs. Cet article explique donc comment utiliser les propres annotations de Spring Boot et certains outils pour générer automatiquement des commentaires et de la documentation sur l'API.

1. Swagger

Swagger est actuellement l'un des outils d'annotation et de génération de documentation d'API Java les plus populaires. Il peut générer automatiquement de la documentation API en analysant les annotations dans les projets Spring, et peut également fournir une interface interactive d'exploration d'API.

Pour utiliser Swagger, vous devez ajouter les dépendances suivantes à votre projet 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>

Ensuite, ajoutez l'annotation @EnableSwagger2 dans la classe de démarrage Spring Boot, comme indiqué Ci-dessous：

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

Ensuite, vous pouvez ajouter les annotations fournies par Swagger à votre méthode Controller pour générer la documentation API.

Par exemple, ce qui suit est un simple 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";
   }
}

En ajoutant l'annotation @ApiOperation et d'autres annotations associées, Swagger générera automatiquement la documentation de l'API et fournira une interface d'exploration interactive de l'API .

Vous pouvez consulter la documentation de votre API en visitant http://localhost:8080/swagger-ui.html.

2. Spring REST Docs

Spring REST Docs est un autre outil de génération d'annotations et de documentation d'API Java qui vous permet d'écrire de la documentation d'API en utilisant les formats AsciiDoc, Markdown ou HTML.

À l'aide de Spring REST Docs, vous devez ajouter les dépendances suivantes à votre projet Spring Boot :

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

Ensuite, ajoutez l'annotation @WebMvcTest dans votre classe de test, comme suit. :

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

En ajoutant les annotations et les descriptions de champs correspondantes, Spring REST Docs générera automatiquement la documentation de l'API et l'enregistrera dans le répertoire /target/generated-snippets, que vous pourrez convertir dans le format de document final.

3. Résumé

Cet article présente deux méthodes pour implémenter l'annotation API et la génération de documents basées sur Spring Boot. Swagger fournit une méthode pratique et facile à utiliser, et les documents générés sont relativement intuitifs et faciles à comprendre, ce qui la rend adaptée aux petits projets ou au développement rapide. Spring REST Docs offre une approche plus flexible et personnalisable, qui peut être appliquée à des projets et des scénarios plus complexes nécessitant une documentation API de meilleure qualité.

Quelle que soit la méthode que vous choisissez, une documentation API correcte, standardisée et claire est essentielle. Elle facilite non seulement la collaboration front-end et back-end, mais contribue également à la maintenance à long terme de votre projet. .

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!