spring boot作为目前最受欢迎的java框架之一，拥有快速开发、高度集成、易于测试等优势。在开发过程中，我们经常需要编写api文档，方便前后端协作以及未来项目维护。
然而，手动编写API文档是十分耗时且容易出错的，因此本文将介绍如何利用Spring Boot自带的注解和一些工具来自动生成API注释和文档。
一、Swagger
Swagger是目前最为流行的Java API注释和文档生成工具之一。它可以通过扫描Spring项目中的注释自动生成API文档，同时还可以提供交互式的API探索界面。
使用Swagger，你需要向你的Spring Boot项目中添加以下依赖：
io.springfox springfox-swagger2 2.9.2 io.springfox springfox-swagger-ui 2.9.2
接着，在Spring Boot的启动类中添加注解@EnableSwagger2，如下所示：
@SpringBootApplication
@EnableSwagger2
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}然后，你可以在你的Controller的方法上加上Swagger提供的注解来生成API文档。
例如，下面是一个简单的UserController：
@RestController
@RequestMapping("/user")
public class UserController {
@ApiOperation(value = "获取用户列表", notes = "获取所有用户的列表")
@GetMapping("/list")
public List 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文档。
本文档主要讲述的是maven使用方法；Maven是基于项目对象模型的（pom），可以通过一小段描述信息来管理项目的构建，报告和文档的软件项目管理工具。Maven将你的注意力从昨夜基层转移到项目管理层。Maven项目已经能够知道 如何构建和捆绑代码，运行测试，生成文档并宿主项目网页。希望本文档会给有需要的朋友带来帮助；感兴趣的朋友可以过来看看
二、Spring REST Docs
Spring REST Docs是另一种Java API注释和文档生成工具，它允许你使用AsciiDoc、Markdown或HTML格式来编写API文档。
使用Spring REST Docs，你需要向你的Spring Boot项目中添加以下依赖：
org.springframework.restdocs spring-restdocs-mockmvc 2.0.2.RELEASE
接着，在你的测试类中添加注解@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目录中，你可以将其转换为最终的文档格式。
三、总结
本文介绍了两种实现基于Spring Boot的API注释和文档生成的方法。Swagger提供了一种方便、易用的方式，生成的文档也比较直观易懂，适合小型项目或快速开发。而Spring REST Docs则提供了更加灵活、可定制的方式，可以适用于更加复杂的项目和对API文档质量要求较高的场景。
无论你选择了哪种方式，API文档的正确、规范和清晰是必不可少的，它不仅方便前后端协作，也有助于你的项目长期维护。
