Asciidoc with Spring Restdocs

Posted on Edited on In Views: Word count in article: 6.7k Reading time ≈ 6 mins.
integrate asciidoc with spring restdocs

Integrate Asciidoc with Spring Restdocs

Preconditon

The following is based on Webflux

1
2
3
asciidoctor version: 3.2.0
spring restdocs version: 2.0.4.RELEASE
dependency management: gradle

Some asciidoctor knowledge:

sourceDir: src/docs/asciidoc

outputDir: ${buildDir}/docs/asciidoc

Configuration

common config

The following config is not a complete configuration.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
// plugins
plugins {
    id 'org.springframework.boot' version '2.3.0.M4'
    id 'io.spring.dependency-management' version '1.0.9.RELEASE'
    id 'java'
    /* for rest docs */
    id 'org.asciidoctor.jvm.convert' version '3.2.0'
}

configurations {
    asciidoctorExtensions
}

ext {
    set('snippetsDir', file('build/generated-snippets'))
    set('springRestdocsVersion', '2.0.4.RELEASE')
}

dependencies {
    testImplementation('org.springframework.boot:spring-boot-starter-test') {
        exclude group: 'org.junit.vintage', module: 'junit-vintage-engine'
    }
    testImplementation 'io.projectreactor:reactor-test'
    /* for rest docs */
    testImplementation "org.springframework.restdocs:spring-restdocs-webtestclient:${springRestdocsVersion}"
    asciidoctorExtensions "org.springframework.restdocs:spring-restdocs-asciidoctor:${springRestdocsVersion}"
}

test {
    outputs.dir snippetsDir
    useJUnitPlatform()
}

asciidoctor {
    configurations 'asciidoctorExtensions'
    dependsOn test
    attributes 'snippets': snippetsDir
    inputs.dir snippetsDir
}

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

create docs/asciidoc/ directory

like this

directory_layout

index.adoc & updateUser.adoc(e.g.)

index.adoc

1
2
3
4
5
6
7
8
9
10
11
12
13
= Blog Restful API
Purple Mystic;
:toc: left
:toc-title: Chapter
:doctype: book
:icons: font
:source-highlighter: highlightjs
:sourcedir: {sourcedir}/user

include::createUser.adoc[]
include::updateUser.adoc[]
include::findUserById.adoc[]
include::findAllUsers.adoc[]

updateUser.adoc

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
== *Backend: updateUser:*

=== Curl request:

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

=== HTTP request:

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

=== HTTP response:

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

=== Request using HTTPie:

include::{snippets}/updateUser/httpie-request.adoc[]

=== Request body:

include::{snippets}/updateUser/request-body.adoc[]

=== Response body:

include::{snippets}/updateUser/response-body.adoc[]

Other solution

  • remove :sourcedir: {sourcedir}/user from index.adoc
  • reconfigure asciidoctor task in build.gradle, like this
1
2
3
4
5
6
7
8
9
10
asciidoctor {
    configurations 'asciidoctorExtensions'
    dependsOn test
    attributes 'snippets': snippetsDir
    inputs.dir snippetsDir
    sources {
        include '**/index.adoc'
    }
    baseDirFollowsSourceFile()
}

Unit Tests

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
package team.star.blog.controller;

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.Mockito;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.reactive.WebFluxTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import org.springframework.context.ApplicationContext;
import org.springframework.http.MediaType;
import org.springframework.restdocs.RestDocumentationContextProvider;
import org.springframework.restdocs.RestDocumentationExtension;
import org.springframework.test.web.reactive.server.WebTestClient;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;
import team.star.blog.pojo.User;
import team.star.blog.service.UserService;

import java.util.List;

import static org.mockito.Mockito.when;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.prettyPrint;
import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
import static org.springframework.restdocs.request.RequestDocumentation.pathParameters;
import static org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.document;
import static org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.documentationConfiguration;

/**
 * @author mystic
 */
@WebFluxTest(UserController.class)
@ExtendWith(RestDocumentationExtension.class)
public class UserControllerTest {
    @Autowired
    private ApplicationContext context;
    private WebTestClient client;
    @MockBean
    private UserService userService;

    @BeforeEach
    void setUp(RestDocumentationContextProvider provider) {
        client = WebTestClient.bindToApplicationContext(context)
            .configureClient()
            .filter(
                documentationConfiguration(provider)
                    .operationPreprocessors()
                    .withRequestDefaults(prettyPrint())
                    .withResponseDefaults(prettyPrint())
            )
            .build();

        User u1 = User.builder().id(1).name("Mystic").build();
        User u2 = User.builder().id(2).name("Ran").build();

        when(userService.findAll()).thenReturn(Flux.fromIterable(List.of(u1, u2)));
        when(userService.findById(Mockito.anyInt())).thenReturn(Mono.just(u1));
        when(userService.save(Mockito.any(User.class))).thenReturn(Mono.just(u2));
    }

    @Test
    void findUserById() {
        client.get().uri("/user/{id}", 1)
            .exchange()
            .expectStatus().isOk()
            .expectBody(User.class)
            .consumeWith(document("findUserById",
                pathParameters(parameterWithName("id").description("User ID"))
            ));

    }

    @Test
    void findAllUsers() {
        client.get().uri("/user").exchange()
            .expectStatus().isOk()
            .expectBodyList(User.class)
            .consumeWith(document("findAllUsers"));
    }

    @Test
    void createUser() {
        User u3 = User.builder().name("cc").build();
        client.post().uri("/user")
            .contentType(MediaType.APPLICATION_JSON)
            .accept(MediaType.APPLICATION_JSON)
            .body(Mono.just(u3), User.class)
            .exchange()
            .expectStatus().isCreated()
            .expectBody()
            .jsonPath("$.id").isEqualTo(2)
            .consumeWith(document("createUser"));
    }

    @Test
    void updateUser() {
        User u2 = User.builder().id(2).name("cc").build();
        client.patch().uri("/user")
            .contentType(MediaType.APPLICATION_JSON)
            .accept(MediaType.APPLICATION_JSON)
            .body(Mono.just(u2), User.class)
            .exchange()
            .expectStatus().isOk()
            .expectBody()
            .jsonPath("$.name").isEqualTo("Ran")
            .consumeWith(document("updateUser"));
    }
}

Source Code

https://github.com/PurpleMystic-star/blog-backend