Spring Boot 第10篇: 用spring Restdocs创建API文档

转载 2018年04月16日 17:03:04

这篇文章将带你了解如何用spring官方推荐的restdoc去生成api文档。本文创建一个简单的springboot工程,将http接口通过Api文档暴露出来。只需要通过 JUnit单元测试和Spring的MockMVC就可以生成文档。

准备工作

  • 你需要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,显示如下,界面还算简洁:

结语

通过单元测试,生存adoc文件,再用adoc文件生存html,只需要简单的几步就可以生成一个api文档的html文件,这个html文件你可以通网站发布出去。整个过程很简单,对代码无任何影响。

源码下载:https://github.com/forezp/SpringBootLearning

参考资料

restdocs

http://docs.spring.io/spring-restdocs/docs/current/reference/html5/

【译】Spring 官方教程:使用 Restdocs 创建 API 文档

原文:Creating API Documentation with Restdocs译者:HoldDie校对:Jitianyu本指南将引导你了解在 Spring 应用程序中为 HTTP 端点(HTT...
  • j3T9Z7H
  • j3T9Z7H
  • 2017-12-27 00:00:00
  • 231

使用spring-restdocs 自动生成接口文档

前言 Spring REST Docs helps you to document RESTful services. It combines hand-written documentation...
  • a87922072
  • a87922072
  • 2017-08-14 17:19:54
  • 4424

8.springboot使用RestDoc创建api文档

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

SpringBoot非官方教程 | 第十篇: 用spring Restdocs创建API文档

这篇文章将带你了解如何用spring官方推荐的restdoc去生成api文档。本文创建一个简单的springboot工程,将http接口通过Api文档暴露出来。只需要通过 JUnit单元测试和Spri...
  • forezp
  • forezp
  • 2017-04-30 16:08:34
  • 32673

spring-restdocs利用测试用例生成API文档,AsciidocFX工具整合

利用spring-restdocs-mockmvc生成API文档 1.项目pom引入依赖的jar包: org.springframework.boot artifactId>spr...
  • seapeak007
  • seapeak007
  • 2017-08-21 17:50:36
  • 395

SpringBoot精藏(八)Spring restDocs创建API文档

一:创建一个SpringBoot项目,引入需要的jar文件
  • qq_28009065
  • qq_28009065
  • 2018-01-15 11:39:43
  • 151

Spring Boot系列之四 自动生成RESTful文档

简介 标题不让写那么长,嗨嗨,原文主题应该为 Spring Boot系列之四 使用Swagger2构建RESTful API文档 不知道会不会影响阅读量... 推荐越来越少了... ...
  • gebitan505
  • gebitan505
  • 2017-04-12 16:37:46
  • 2347

SpringBoot&Swagger构建REST API并生成API文档

概述 开始 注解说明 运行效果 API文档访问与调试概述通常我们要构建API 服务,自然少不了文档,但由于API与文档的分离使得我们每次对API进行的更改都需要再去修改文档后同步文档,不但编写稳定繁琐...
  • zjcjava
  • zjcjava
  • 2017-04-19 18:36:56
  • 3771

Spring Boot中使用Swagger2构建RESTful API文档

转载声明:商业转载请联系作者获得授权,非商业转载请注明出处 © wekri 随着时间推移,不断修改接口实现的时候都必须同步修改接口文档,而文档与代码又处于两个不同的媒介,除非有严格的管理机制...
  • Eacter
  • Eacter
  • 2017-02-23 15:01:25
  • 3999

Spring boot 官方文档

  • 2015年04月29日 23:38
  • 1.2MB
  • 下载
收藏助手
不良信息举报
您举报文章:Spring Boot 第10篇: 用spring Restdocs创建API文档
举报原因:
原因补充:

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