企业分布式微服务云SpringCloud SpringBoot mybatis (二十二)Restdoc生成api文档

原创 2018年02月12日 10:09:02

准备工作

  • 你需要15min
  • Jdk 1.8
  • maven 3.0+
  • idea

创建工程

引入依赖,其pom文件:

<dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <dependency>
            <groupId>org.springframework.restdocs</groupId>
            <artifactId>spring-restdocs-mockmvc</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

通过@SpringBootApplication,开启springboot

@SpringBootApplication
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

在springboot通常创建一个controller:

@RestController
public class HomeController {

    @GetMapping("/")
    public Map<String, Object> greeting() {
        return Collections.singletonMap("message", "Hello World");
    }

}

启动工程,访问localhost:8080,浏览器显示:

{“message”:”Hello World”}

证明接口已经写好了,但是如何通过restdoc生存api文档呢

Restdoc,通过单元测试生成api文档

restdocs是通过单元测试生存snippets文件,然后snippets根据插件生成htm文档的。

建一个单元测试类:

@RunWith(SpringRunner.class)
@WebMvcTest(HomeController.class)
@AutoConfigureRestDocs(outputDir = "target/snippets")
public class WebLayerTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    public void shouldReturnDefaultMessage() throws Exception {
        this.mockMvc.perform(get("/")).andDo(print()).andExpect(status().isOk())
                .andExpect(content().string(containsString("Hello World")))
                .andDo(document("home"));
    }
}

其中,@ AutoConfigureRestDocs注解开启了生成snippets文件,并指定了存放位置。

启动单元测试,测试通过,你会发现在target文件下生成了一个snippets文件夹,其目录结构如下:

└── target
    └── snippets
        └── home
            └── httpie-request.adoc
            └── curl-request.adoc
            └── http-request.adoc
            └── http-response.adoc

默认情况下,snippets是Asciidoctor格式的文件,包括request和reponse,另外其他两种httpie和curl两种流行的命令行的http请求模式。

到目前为止,只生成了Snippets文件,需要用Snippets文件生成文档。

怎么用Snippets

创建一个新文件src/main/asciidoc/index.adoc :

= 用 Spring REST Docs 构建文档

This is an example output for a service running at http://localhost:8080:

.request
include::{snippets}/home/http-request.adoc[]

.response
include::{snippets}/home/http-response.adoc[]

这个例子非常简单,通过单元测试和一些简单的配置就能够得到api文档了。

adoc的书写格式,参考:http://docs.spring.io/spring-restdocs/docs/current/reference/html5/,这里不多讲解。

需要使用asciidoctor-maven-plugin插件,在其pom文件加上:

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <executions>
        <execution>
            <id>generate-docs</id>
            <phase>prepare-package</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <sourceDocumentName>index.adoc</sourceDocumentName>
                <backend>html</backend>
                <attributes>
                    <snippets>${project.build.directory}/snippets</snippets>
                </attributes>
            </configuration>
        </execution>
    </executions>
</plugin>

这时只需要通过mvnw package命令就可以生成文档了。 
在/target/generated-docs下有个index.html,打开这个html,显示如下,界面还算简洁:

Paste_Image.png

源码来源

8.springboot使用RestDoc创建api文档

1.建立过程 (1)pom.xml 主要是需要两个依赖 restDoc依赖生成snippets文件 mvn插件依赖将snippets文件变成http文档 ...
  • qq_34448345
  • qq_34448345
  • 2017年12月13日 18:06
  • 106

springboot微服务搭建(一):整合mybatis配置(第一种方式)

研究一下在写。
  • sinat_32519815
  • sinat_32519815
  • 2017年11月10日 15:54
  • 34

企业分布式微服务云SpringCloud SpringBoot mybatis (二十)整合 beatlsql

整合阶段由于springboot没有对 beatlsql的快速启动装配,所以需要我自己导入相关的bean,包括数据源,包扫描,事物管理器等。在application加入以下代码:@Bean(initM...
  • qq_40342510
  • qq_40342510
  • 2018年02月12日 09:57
  • 60

整合Spring Cloud分布式微服务云架构集成项目

Spring Cloud Config配置管理工具包,让你可以把配置放到远程服务器,集中化管理集群配置,目前支持本地存储、Git以及Subversion......
  • qq_40342510
  • qq_40342510
  • 2017年10月27日 09:48
  • 218

springboot+mybatis 查询一下

实现一下springboot Controller查询一段数据application.propertiesspring.datasource.url=jdbc:mysql://localhost:33...
  • qq_35101463
  • qq_35101463
  • 2017年12月10日 21:08
  • 51

面向微服务的企业云计算架构转型

云计算的本质是提高效率,而不是降低成本,公有云就是要提高社会的效率,私有云就是要提高 IT 的效率。从这个角度看,实施云计算就是做精益运营,而微服务架构为精益运营提供了架构上的保证,因为微服务是小的、...
  • jiaoly
  • jiaoly
  • 2016年08月22日 14:55
  • 2859

SpringCloud(一)构建SpringBoot微服务

本篇文章将会展示两个springboot项目,一个是provider(服务提供者),另一个是consumer(服务消费者).基本思路是provider通过查询数据库返回信息,consumer通过res...
  • zzzzzz55300411
  • zzzzzz55300411
  • 2017年01月09日 22:47
  • 1691

基于Spring Boot和Spring Cloud实现微服务架构学习(四)-Spring Cloud总结

基于Spring Boot和Spring Cloud框架开发的微服务架构学习(四)-Spring Cloud总结 Spring Cloud包含了多个子项目(针对分布式系统中涉及的多个不同开源产品),之...
  • zeb_perfect
  • zeb_perfect
  • 2016年07月24日 00:48
  • 77799

企业分布式微服务云SpringCloud SpringBoot mybatis (二十一)构建restful API

引入依赖在pom文件引入mybatis-spring-boot-starter的依赖: &lt;dependency&gt; &lt;groupId&a...
  • qq_40342510
  • qq_40342510
  • 2018年02月12日 10:01
  • 49

企业分布式微服务云SpringCloud SpringBoot mybatis (三)Spring Boot构建RESTful API与单元测试

首先,回顾并详细说明一下在快速入门中使用的@Controller、@RestController、@RequestMapping注解。如果您对Spring MVC不熟悉并且还没有尝试过快速入门案例...
  • qq_40342510
  • qq_40342510
  • 2018年02月05日 09:59
  • 212
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:企业分布式微服务云SpringCloud SpringBoot mybatis (二十二)Restdoc生成api文档
举报原因:
原因补充:

(最多只允许输入30个字)