1. 前言

现在文档大部分都是用swagger来生成的,但是springboot官网也提供了 spring rest doc 组件用于生成文档,因为java项目基本上都是用spring boot来创建的,所以个人倾向于spring rest doc.

2. 实现

spring rest doc 主要是基于unit单元测试实现的,添加依赖

testCompile 'org.junit.jupiter:junit-jupiter-api'
    testRuntime 'org.junit.jupiter:junit-jupiter-engine'
    testCompile 'org.springframework.restdocs:spring-restdocs-mockmvc'
    asciidoctor 'org.springframework.restdocs:spring-restdocs-asciidoctor'

添加asciidoctor配置,这块主要是配置生成snippets文件,

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

test {
    outputs.dir snippetsDir
    useJUnitPlatform()
}
asciidoctor { 
    inputs.dir snippetsDir 
    dependsOn test 
}
bootJar {
    dependsOn asciidoctor 
    from ("${asciidoctor.outputDir}/html5") { 
        into 'static/docs'
    }
}

添加单元测试

@SpringBootTest
@ExtendWith({RestDocumentationExtension.class, SpringExtension.class})
public class BaseTestConfig {
    @Autowired
    protected WebApplicationContext context;

    protected ObjectMapper mapper = new ObjectMapper();
    
    protected MockMvc mockMvc;

    @BeforeEach
    public void setUp(RestDocumentationContextProvider restDocumentation) {
        this.mockMvc = MockMvcBuilders.webAppContextSetup(context)
                .apply(documentationConfiguration(restDocumentation).uris().withPort(8090)).build();
    }
}

public class MyContractTest extends BaseTestConfig {
    @Test
    public void myContract() throws Exception {
        MyContract myContract = new MyContract();
        myContract.setName("test1");
        myContract.setUser("test2");
        
        System.out.println(mapper.writeValueAsString(myContract));
        this.mockMvc.perform(post("/contract").content(mapper.writeValueAsString(myContract)).contentType(MediaType.APPLICATION_JSON).accept(MediaType.APPLICATION_JSON)).andExpect(status().isOk())
                .andDo(document("contract",
                        requestFields(attributes(key("name").value("Fields for user creation"),key("user").value("Fields for user creation"))
                                ,fieldWithPath("name").description("The user's name")
                                .attributes(key("constraints")
                                        .value("Must not be null. Must not be empty")),
                                fieldWithPath("user").description("The user's name")
                                .attributes(key("constraints")
                                        .value("Must not be null. Must not be empty"))),
                        
                        responseFields(fieldWithPath("resultCode").description("状态"))));
    }

}

controller类是

@RestController
public class ContractController {
    
    @PostMapping("/contract")
    public Map<String, String> postContact(@RequestBody MyContract mycontract) {
        System.out.println("Accepted mycontract");
        return Collections.singletonMap("resultCode", "0");
    }
    
    
}

运行下面这个命令

 

我们就可以发现 

\build\asciidoc\html5 在这个目录下生成了 html文件

 

 打开后就显示出了文档界面,需要写出漂亮的界面还要学习asciidoc文档的语法