spring boot作为目前最受欢迎的java框架之一，拥有快速开发、高度集成、易于测试等优势。在开发过程中，我们经常需要编写api文档，方便前后端协作以及未来项目维护。
然而，手动编写api文档是十分耗时且容易出错的，因此本文将介绍如何利用spring boot自带的注解和一些工具来自动生成api注释和文档。
一、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@enableswagger2public 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<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文档。
二、spring rest docs
spring rest docs是另一种java api注释和文档生成工具，它允许你使用asciidoc、markdown或html格式来编写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目录中，你可以将其转换为最终的文档格式。
三、总结
本文介绍了两种实现基于spring boot的api注释和文档生成的方法。swagger提供了一种方便、易用的方式，生成的文档也比较直观易懂，适合小型项目或快速开发。而spring rest docs则提供了更加灵活、可定制的方式，可以适用于更加复杂的项目和对api文档质量要求较高的场景。
无论你选择了哪种方式，api文档的正确、规范和清晰是必不可少的，它不仅方便前后端协作，也有助于你的项目长期维护。
以上就是如何实现基于spring boot的api注释和文档生成的详细内容。