Spring Boot를 기반으로 API 주석 및 문서 생성을 구현하는 방법

Spring Boot는 현재 가장 인기 있는 Java 프레임워크 중 하나로 빠른 개발, 높은 통합성 및 쉬운 테스트라는 장점을 가지고 있습니다. 개발 프로세스 중에 프런트엔드 및 백엔드 협업과 향후 프로젝트 유지 관리를 용이하게 하기 위해 API 문서를 작성해야 하는 경우가 많습니다.

그러나 API 문서를 수동으로 작성하는 것은 시간이 많이 걸리고 오류가 발생하기 쉬우므로 이 기사에서는 Spring Boot의 자체 주석과 일부 도구를 사용하여 API 주석 및 문서를 자동으로 생성하는 방법을 소개합니다.

1. 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);
   }
}

그런 다음 이를 컨트롤러는 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 문서를 볼 수 있습니다.

2. Spring REST Docs

Spring REST Docs는 AsciiDoc, Markdown 또는 HTML 형식을 사용하여 API 문서를 작성할 수 있는 또 다른 Java 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 디렉터리에 저장하며, 이를 최종 문서 형식으로 변환할 수 있습니다.

3. 요약

이 글에서는 Spring Boot를 기반으로 API Annotation과 Document 생성을 구현하는 두 가지 방법을 소개합니다. Swagger는 편리하고 사용하기 쉬운 방법을 제공하며, 생성된 문서는 비교적 직관적이고 이해하기 쉬워 소규모 프로젝트나 빠른 개발에 적합합니다. Spring REST Docs는 더 높은 품질의 API 문서가 필요한 더 복잡한 프로젝트 및 시나리오에 적용할 수 있는 더 유연하고 사용자 정의 가능한 접근 방식을 제공합니다.

어떤 방법을 선택하든 API 문서는 정확하고 표준화되어 있으며 명확해야 합니다. 이는 프런트엔드 및 백엔드 협업을 촉진할 뿐만 아니라 프로젝트의 장기적인 유지 관리에도 도움이 됩니다.

위 내용은 Spring Boot를 기반으로 API 주석 및 문서 생성을 구현하는 방법의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!