使用Spring REST docs & JUnit 5创建API服务文档

01/07 14:17
阅读数 102

在前后端分离盛兴的时代,REST API是前后端通信的必要途径。一个好的REST API,不仅符合RESTful规范,还需要有一个高质量的API服务文档。对于API服务文档来讲,难点不是创建文档,而是如何更高效的维护文档,让文档和代码的变化保持同步。错误的API服务文档,会让使用者走入歧途,还不如没有文档的好。

Spring REST Docs

值得开心的是,在Spring全家桶中就用这样的工具来满足我们的要求。Spring REST Docs采用手写文档和自动生成片段相结合的方式来创建API文档。Asciidoc是手写文档的格式,这种文档格式在Spring全家桶中广广泛使用,Spring Reference document就是使用它生成的。

Spring REST Docs依据单元测试时所需的HTTP请求及其响应自动生成单元测试的文档。

配置

我们都知道现在流行的Java项目管理工具有Maven和Gradle两种。在Spring Framework的高级版本,将项目管理工具从Maven切换到了Gradle。因此,我们也采用Gradle来管理我们的项目。

build.gradle配置

buildscript {
   repositories {
       mavenCentral()
   }
   dependencies {
       classpath 'org.springframework.boot:spring-boot-gradle-plugin:2.1.8.RELEASE'
   }
}

plugins {
   id "org.asciidoctor.convert" version "1.5.9.2"
}

apply plugin: 'java'
apply plugin: 'org.springframework.boot'
apply plugin: 'eclipse'
apply plugin: 'io.spring.dependency-management'

repositories {
   mavenLocal()
   maven { url 'https://repo.spring.io/libs-snapshot' }
   mavenCentral()
}


sourceCompatibility = 1.8
targetCompatibility = 1.8

ext {
   snippetsDir = file('build/generated-snippets')
}

ext['spring-restdocs.version'] = '2.0.5.BUILD-SNAPSHOT'

dependencies {
   asciidoctor 'org.springframework.restdocs:spring-restdocs-asciidoctor'

   compile 'org.springframework.boot:spring-boot-starter-web'

   testCompile('org.springframework.boot:spring-boot-starter-test') {
       exclude group: 'junit', module: 'junit;'
   }
   testCompile 'org.springframework.restdocs:spring-restdocs-mockmvc'
   testCompile 'org.junit.jupiter:junit-jupiter-api'
   testRuntime 'org.junit.jupiter:junit-jupiter-engine'
}

test {
   outputs.dir snippetsDir
   useJUnitPlatform()
}

asciidoctor {
   inputs.dir snippetsDir
   dependsOn test
}

bootJar {
   dependsOn asciidoctor
   from("${asciidoctor.outputDir}/html5") {
       into 'static/docs'
   }
}

eclipseJdt.onlyIf { false }
cleanEclipseJdt.onlyIf { false }



































































在这里,我们的单元测试JUnit使用JUnit 5版本,它在Spring 5中得到了很好的支持。

像其他的Spring Boot项目一样,我们需要创建一个Application。

package io.github.tinyking.spotlighs.restdocs;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
* RestdocsApplication.
*
* @author tinyking
* @version 1.0
* @since 2019/10/15
*/






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













创建一个简单的Controller,用来做的HTTP API测试

package io.github.tinyking.spotlighs.restdocs;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
* SampleController.
*
* @author tinyking
* @version 1.0
* @since 2019/10/15
*/






@RestController
public class SampleController {

   @GetMapping("/")
   public String index() {
       return "Hello, World";
   }
}















接下来,我们需要为Application创建一个使用JUnit 5单元测试

package io.github.tinyking.spotlighs.restdocs;

import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.restdocs.RestDocumentationContextProvider;
import org.springframework.restdocs.RestDocumentationExtension;
import org.springframework.test.context.junit.jupiter.SpringExtension;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.context.WebApplicationContext;

/**
* RestdocsApplicationTest.
*
* @author tinyking
* @version 1.0
* @since 2019/10/15
*/






@SpringBootTest
@ExtendWith({RestDocumentationExtension.class, SpringExtension.class})
public class RestdocsApplicationTest {

   @Autowired
   private WebApplicationContext wac;

   private MockMvc mockMvc;

   @BeforeEach
   public void setup(RestDocumentationContextProvider restDocumentationContextProvider) {
       this.mockMvc = MockMvcBuilders.webAppContextSetup(wac)
               .apply(documentationConfiguration(restDocumentationContextProvider)).build();
   }

   @Test
   public void sample() throws Exception {
       this.mockMvc.perform(get("/"))
               .andExpect(status().isOk())
               .andDo(document("sample"));
   }
}












































手写文档

就像一开始说的,我们需要手写文档+自动生成来实现REST API服务文档。上面所有的操作都是为了自动生成片段,下面我们来创建一个手写文档。

spotlight-spring-restdocs/src/docs/asciidoc/index.adoc

= 基于JUnit5的Spring restdocs实例
tinyking;
:doctype: book
:icons: font
:source-highlighter: highlightjs

Http curl请求示例:

include::{snippets}/sample/curl-request.adoc[]

Http请求:

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

Http响应:

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


















这就是一个简单的手写+自动的文档,里面的curl-request.adoc、http-request.adoc、

http-response.adoc都是根据单元测试自动生成的。

生成API文档

接下来我们通过命名来生成API文档

gradle bootJar

执行完成后,可以找到build/asciidoc/html5/index.html ,直接在浏览器中打开,如下:

图片

总结

通过使用Spring REST docs,可以让我们快速的生成API服务文档,基于单元测试可以确保API文档和代码保持一致。并且Spring REST Docs的方式不像Swagger,它不会***我们的业务代码,保证我们代码的整洁性。


展开阅读全文
打赏
0
0 收藏
分享
加载中
更多评论
打赏
0 评论
0 收藏
0
分享
返回顶部
顶部