So implementieren Sie API-Annotationen und Dokumentgenerierung basierend auf Spring Boot

Spring Boot ist derzeit eines der beliebtesten Java-Frameworks und bietet die Vorteile einer schnellen Entwicklung, einer hohen Integration und eines einfachen Testens. Während des Entwicklungsprozesses müssen wir häufig API-Dokumente schreiben, um die Front-End- und Back-End-Zusammenarbeit und die zukünftige Projektwartung zu erleichtern.

Das manuelle Schreiben der API-Dokumentation ist jedoch sehr zeitaufwändig und fehleranfällig. In diesem Artikel wird daher erläutert, wie Sie die eigenen Annotationen von Spring Boot und einige Tools verwenden, um API-Kommentare und Dokumentation automatisch zu generieren.

1. Swagger

Swagger ist derzeit eines der beliebtesten Java-API-Annotations- und Dokumentgenerierungstools. Es kann durch Scannen von Anmerkungen in Spring-Projekten automatisch eine API-Dokumentation generieren und außerdem eine interaktive Schnittstelle zur API-Erkundung bereitstellen.

Um Swagger zu verwenden, müssen Sie die folgenden Abhängigkeiten zu Ihrem Spring Boot-Projekt hinzufügen:

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

Dann fügen Sie die Annotation @EnableSwagger2 in der Spring Boot-Startup-Klasse hinzu, wie unten gezeigt:

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

Dann können Sie sie hinzufügen Ihr Controller Fügen Sie von Swagger bereitgestellte Anmerkungen zur Methode hinzu, um API-Dokumentation zu generieren.

Das Folgende ist beispielsweise ein einfacher 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";
   }
}

Durch Hinzufügen der Annotation @ApiOperation und anderer verwandter Annotationen generiert Swagger automatisch eine API-Dokumentation und stellt eine interaktive API-Erkundungsschnittstelle bereit.

Sie können Ihre API-Dokumentation anzeigen, indem Sie http://localhost:8080/swagger-ui.html besuchen.

2. Spring REST Docs

Spring REST Docs ist ein weiteres Java-API-Annotations- und Dokumentationsgenerierungstool, mit dem Sie API-Dokumentation im AsciiDoc-, Markdown- oder HTML-Format schreiben können.

Mit Spring REST Docs müssen Sie die folgenden Abhängigkeiten zu Ihrem Spring Boot-Projekt hinzufügen:

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

Als nächstes fügen Sie die Annotation @WebMvcTest wie folgt in Ihre Testklasse ein:

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

indem Sie die entsprechenden Annotationen und Felder Beschreibung, Spring hinzufügen REST Docs generiert automatisch eine API-Dokumentation und speichert sie im Verzeichnis /target/generated-snippets, und Sie können sie in das endgültige Dokumentationsformat konvertieren.

3. Zusammenfassung

In diesem Artikel werden zwei Methoden zur Implementierung von API-Annotationen und Dokumentgenerierung basierend auf Spring Boot vorgestellt. Swagger bietet eine bequeme und benutzerfreundliche Methode. Die generierten Dokumente sind relativ intuitiv und leicht zu verstehen, sodass sie für kleine Projekte oder schnelle Entwicklungen geeignet sind. Spring REST Docs bietet einen flexibleren und anpassbareren Ansatz, der auf komplexere Projekte und Szenarien angewendet werden kann, die eine qualitativ hochwertigere API-Dokumentation erfordern.

Egal für welche Methode Sie sich entscheiden, es ist wichtig, dass die API-Dokumentation korrekt, standardisiert und klar ist. Sie erleichtert nicht nur die Front-End- und Backend-Zusammenarbeit, sondern hilft auch bei der langfristigen Wartung Ihres Projekts.

Das obige ist der detaillierte Inhalt vonSo implementieren Sie API-Annotationen und Dokumentgenerierung basierend auf Spring Boot. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!