Spring BootをベースにしたAPIアノテーションとドキュメント生成を実装する方法

Spring Boot は現在最も人気のある Java フレームワークの 1 つであり、迅速な開発、高度な統合、簡単なテストという利点があります。開発プロセスでは、フロントエンドとバックエンドのコラボレーションや将来のプロジェクトのメンテナンスを容易にするために API ドキュメントを作成する必要があることがよくあります。

ただし、API ドキュメントを手動で作成するのは非常に時間がかかり、エラーが発生しやすいため、この記事では、Spring Boot 独自のアノテーションと、API コメントとドキュメントを自動的に生成するいくつかのツールを使用する方法を紹介します。

1. Swagger

Swagger は、現在最も人気のある Java API アノテーションおよびドキュメント生成ツールの 1 つです。 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 ドキュメントを作成できる、もう 1 つの Java API アノテーションおよびドキュメント生成ツールです。

Spring REST ドキュメントを使用して、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 アノテーションとドキュメント生成を実装する 2 つの方法を紹介します。 Swagger は便利で使いやすいメソッドを提供し、生成されるドキュメントは比較的直観的で理解しやすいため、小規模なプロジェクトや迅速な開発に適しています。 Spring REST Docs は、より柔軟でカスタマイズ可能なアプローチを提供し、高品質の API ドキュメントを必要とするより複雑なプロジェクトやシナリオに適用できます。

どの方法を選択する場合でも、API ドキュメントが正しく、標準化され、明確であることが重要です。これにより、フロントエンドとバックエンドのコラボレーションが促進されるだけでなく、プロジェクトの長期的なメンテナンスにも役立ちます。

以上がSpring BootをベースにしたAPIアノテーションとドキュメント生成を実装する方法の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。