对于app开发来说，必须需要有相应的api文档，一般最基础的就是用markdown工具来撰写api文档。当对于开发人员来说，是总会想着寻找更方便撰写，测试，对接前端开发的文档生成的工具。
其实这方面的工具很多：手动撰写的也很多，很多都带有mock测试功能。方便前端对接时使用。
国内的也不少：
RAP：动态生成模拟数据，实时测试等功能。
eoLinker：基于云端的api管理工具，同时提供在线协作，测试等的功能。
SBDoc：SBDoc是一个商业化开源产品，完全免费。无论你是前端工程师，还是后端工程师，接口永远都是两者交互的桥梁，所以SBDoc专为中小型团队量身打造，旨在解决接口的管理，测试与数据生成，实现真正的一体化解决方案。
Apizza - 为极客打造的api管理工具。
easyApi：有分免费和收费，但只支持在线版本的api管理。
CrapApi：一个由anjularjs+bootstrap+springMVC搭建的免费开源的API接口、文档管理系统（应用接口管理系统）。
showDoc：国内的api 管理工具，比较简洁。https://www.showdoc.cc/demo?page_id=10
小幼鸡：也是api 管理工具，差不多，自己可以比较试用，
NEI：团队协作工具，其实也是在文档等包括api接口的测试等的工具。https://nei.netease.com/
apiview：不多说就是一个工具。https://www.apiview.com/
apidoc：apidoc可以根据代码注释生成web api；没什么侵入性，可是学习成本稍微高点，要了解很多注释里使用到的注解
外国的Swagger 是一款java的api 生成工具，不过是代码侵入的形式，功能是很强大啊。可是代码里要加很多注解，让人别扭。
： 是比较好的api管理框架吧!
当然还有很多这种api管理工具，基本都是在云应用上，至少都有免费的。最好寻找离线的工具，可以在本地部署使用为最优了。
==========================================================================
下面重点介绍的是spring-rest-docs的使用。
spring-rest-docs是一个测试驱动的spring组件，他能生成测试成功的接口进行文档生成，支持markdown的转换或者html的转化，对于文档对接，其实也够了，缺点就是无法像其他工具那样模拟测试数据，前端在对接的时候，可以直接调用模拟数据，尤其对于赶进度的接口，可能是先写接口，再写实现，那么这样的话，就有点不适合。
但他的强大之处，就是可以自动生成文档，而且是经过测试过的接口，减去一些不必要的撰写工作，相对于Swagger来说，没有任何代码的依赖侵入。所以在实际的spring那套开发框架下，还是建议使用，他确实很不错。如果真的需要用到其他系统化的api管理工具，可以把markdown再导入到管理工具中去，即可。
另外apidoc 也不错，也是可以考虑使用的。
--------------------------------------------------------------------------------
spring-boot 整合 spring-rest-docs
1，pom.xml
4.0.0 com.ouyang boss 0.0.1-SNAPSHOT jar boss Demo project for Spring Boot org.springframework.boot spring-boot-starter-parent 1.5.4.RELEASE UTF-8 UTF-8 1.8 org.springframework.boot spring-boot-starter-aop org.springframework.boot spring-boot-starter-cache org.springframework.boot spring-boot-starter-data-redis org.mybatis.spring.boot mybatis-spring-boot-starter 1.3.0 org.springframework.session spring-session org.springframework.boot spring-boot-starter-thymeleaf org.springframework.boot spring-boot-starter-web org.springframework.boot spring-boot-starter-websocket mysql mysql-connector-java runtime org.springframework.boot spring-boot-configuration-processor true org.springframework.boot spring-boot-starter-test test org.springframework.restdocs spring-restdocs-mockmvc test com.auth0 java-jwt 3.2.0 io.jsonwebtoken jjwt 0.7.0 com.google.code.gson gson 2.8.0 org.springframework.boot spring-boot-maven-plugin org.apache.maven.plugins maven-surefire-plugin **/*Test.java org.asciidoctor asciidoctor-maven-plugin 1.5.2 generate-docs prepare-package process-asciidoc html book ${project.build.directory}/generated-snippets
2,写测试类
@RunWith(SpringRunner.class)@WebMvcTest(TestController.class)@AutoConfigureRestDocs(outputDir = "target/generated-snippets")public class SpringRest2 { @Autowired private MockMvc mockMvc; @Test public void shouldReturnDefaultMessage() throws Exception { this.mockMvc.perform(get("/xiaofeng").param("xiaobing", "Tester").accept(MediaType.APPLICATION_JSON)) .andExpect(status().isOk()) .andDo(document("index2", requestParameters( parameterWithName("xiaobing").description("xiaobing is autoSelected avaible")))); } // @Test // public void shouldReturnDefaultMessage2() throws Exception { // this.mockMvc.perform(get("/api/liu").accept(MediaType.APPLICATION_JSON)) // .andExpect(status().isOk()) // .andDo(document("index")); // } } 3，进行junit测试后在target目录下会生成
然后再手动配置接口展示的文档：
这里需要建立相应的文档，并建立index.adoc文件。{snippets} 就是你配置在asciidoctor-maven-plugin插件里的snippets属性
4，生成html文档
在控制台输入： mvnw package （或者mvn package）
会在target/generated-docs 里面生成对应的html文档。
还有更好的用法，可以查看官方文档：
http://docs.spring.io/spring-restdocs/docs/1.1.0.RELEASE/reference/html5/
intellj可以按照asciiDoc插件 方便查看文档
参考：spring-rest-docs https://github.com/sumit-samaddar/spring-rest-docs
官方地址：http://docs.spring.io/spring-restdocs/docs/1.1.0.RELEASE/reference/html5/