以前接口文档都是用swagger2在线文档,最近升级为spring boot2 + webflux反应式编程后,swagger2不支持webflux,无法使用,因此文档生成改为官方的spring rest docs,实践过程中因为英文不咋地走了一些弯路,在这里记录一下吧。

1. 首先就是依赖和gradle插件

官方的gradle依赖,要注意的地方是plugins的位置。本文是markdown书写缺失一些asciidoc的显示

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

dependencies {
    asciidoctor 'org.springframework.restdocs:spring-restdocs-asciidoctor:2.0.2.RELEASE' 
    testCompile "org.springframework.restdocs:spring-restdocs-webtestclient:2.0.2.RELEASE" //如果为mvc换成mvc测试相关依赖
}

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

test { 
    outputs.dir snippetsDir
}

asciidoctor { 
    inputs.dir snippetsDir 
    dependsOn test 
}
//spring boot打jar包的时候将生成的html5资源加入
bootJar {
    dependsOn asciidoctor
    from ("${asciidoctor.outputDir}/html5") {
        into 'static/public/docs'
    }
}
//Apply the Asciidoctor plugin.
//Add a dependency on spring-restdocs-asciidoctor in the asciidoctor configuration. This will automatically configure the snippets attribute for use in your .adoc files to point to build/generated-snippets. It will also allow you to use the operation block macro.
//Add a dependency on spring-restdocs-mockmvc in the testCompile configuration. If you want to use REST Assured rather than MockMvc, add a dependency on spring-restdocs-restassured instead.
//Configure a property to define the output location for generated snippets.
//Configure the test task to add the snippets directory as an output.
//Configure the asciidoctor task
//Configure the snippets directory as an input.
//Make the task depend on the test task so that the tests are run before the documentation is created.

2. 开始编写接口单元测试

代码如下,其中responseFields和requestFields的相关字段约束参考官网


import com.fasterxml.jackson.annotation.JsonIgnoreProperties; import com.google.common.collect.Lists; import lombok.extern.slf4j.Slf4j; import org.junit.Before; import org.junit.Rule; import org.junit.Test; import org.junit.runner.RunWith; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.autoconfigure.web.reactive.SpringBootWebTestClientBuilderCustomizer; import org.springframework.boot.test.context.SpringBootTest; import org.springframework.boot.web.codec.CodecCustomizer; import org.springframework.context.ApplicationContext; import org.springframework.restdocs.JUnitRestDocumentation; import org.springframework.restdocs.constraints.ConstraintDescriptions; import org.springframework.test.context.ActiveProfiles; import org.springframework.test.context.junit4.SpringRunner; import org.springframework.test.web.reactive.server.WebTestClient; import reactor.core.publisher.Mono; import java.util.Collection; import java.util.Map; import java.util.stream.Collectors; import static org.springframework.restdocs.payload.PayloadDocumentation.*; import static org.springframework.restdocs.snippet.Attributes.key; import static org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.document; import static org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.documentationConfiguration; @RunWith(SpringRunner.class) @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) @ActiveProfiles("dev") @Slf4j public class DocsGen { @Rule public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation(); @Autowired public ApplicationContext context; private WebTestClient webTestClient; @Before public void setUp() { this.webTestClient = WebTestClient.bindToApplicationContext(context) .configureClient().baseUrl("http://api.example.com/") .filter(documentationConfiguration(restDocumentation)) .build(); } @Test public void loginTest() { final ReactiveSecurityConfig.BUser bUser = new ReactiveSecurityConfig.BUser(); bUser.setUsername("super"); bUser.setPassword("12345"); ConstraintDescriptions userConstraints = new ConstraintDescriptions(ReactiveSecurityConfig.BUser.class); webTestClient .post().uri("/api/login") .body(Mono.just(bUser), ReactiveSecurityConfig.BUser.class) .exchange().expectStatus().isOk() .expectBody() .consumeWith(document("login", //生成adoc文档所在文件夹名称 requestFields(fieldWithPath("username") .description("用户名") .attributes(key("constraints").value(userConstraints.descriptionsForProperty("username"))), fieldWithPath("password") .description("用户密码").attributes(key("constraints").value(userConstraints.descriptionsForProperty("password"))) ), responseFields(fieldWithPath("id").description("id").attributes(key("constraints").value("")), fieldWithPath("username").description("用户名").attributes(key("constraints").value("")), fieldWithPath("agentId").description("企业号应用名称").attributes(key("constraints").value("")), fieldWithPath("lastUpdatedAt").description("最近登录时间").attributes(key("constraints").value("")), fieldWithPath("status").description("状态").attributes(key("constraints").value("")), fieldWithPath("enabled").description("是否启用").attributes(key("constraints").value("")), fieldWithPath("accountNonExpired").description("是否过期").attributes(key("constraints").value("")), fieldWithPath("handler").description("null").attributes(key("constraints").value("")), fieldWithPath("authorities[].authority").description("授权信息").attributes(key("constraints").value("")), fieldWithPath("accountNonLocked").description("是否没有被锁").attributes(key("constraints").value("")), fieldWithPath("credentialsNonExpired").description("认证是否过期").attributes(key("constraints").value(""))))); } }

跑一下单元测试试试,跑完后看一下build文件夹目录如下,框框里面就是生成的adoc文件,adoc文件是一种毕markdown更强档的书写文档格式,spring官网文档和很多大公司的文档都由其编写,adoc文档参考AsciiDoc 语法快速参考

request-fields.adoc和response-fields.adoc默认没有,需要在增加如图配置。具体内容基本相同

request-fields.adoc和response-fields.adoc具体内容

|===
|路径|类型|描述|约束
{{#fields}}
|{{#tableCellContent}}`{{path}}`{{/tableCellContent}}
|{{#tableCellContent}}`{{type}}`{{/tableCellContent}}
|{{#tableCellContent}}{{description}}{{/tableCellContent}}
|{{#tableCellContent}}{{constraints}}{{/tableCellContent}}
{{/fields}}
|===

打开http-request.adoc、http-response.adoc看看,发现json都是未格式化的,很不美观。没关系改下配置让其美化一下吧,美化的关键是在ObjectMapper的打印配置,修改如下:

  • 先全局序列化消息配置

@Configuration @EnableScheduling public class AppConfig implements ApplicationContextAware { @Override public void setApplicationContext(ApplicationContext applicationContext) { AppContextUtils.setCtx(applicationContext); } /** * XML报文序列化器 * JsonInclude.Include.NON_NULL 序列化是忽略null字段 * SerializationFeature.FAIL_ON_EMPTY_BEANS, false懒加载异常消除 * * @return xmlMapper */ @Bean public XmlMapper xmlMapper() { final XmlMapper xmlMapper = new XmlMapper(); xmlMapper.setSerializationInclusion(JsonInclude.Include.NON_NULL); xmlMapper.configure(SerializationFeature.FAIL_ON_EMPTY_BEANS, false); xmlMapper.enable(SerializationFeature.INDENT_OUTPUT); return xmlMapper; } /** * Json报文序列化器 * JsonInclude.Include.NON_NULL 序列化是忽略null字段 * SerializationFeature.FAIL_ON_EMPTY_BEANS, false懒加载异常消除 * * @return xmlMapper */ @Bean public ObjectMapper objectMapper() { return Jackson2ObjectMapperBuilder.json() .serializationInclusion(JsonInclude.Include.NON_NULL) .build() .configure(SerializationFeature.FAIL_ON_EMPTY_BEANS, false) .enable(SerializationFeature.INDENT_OUTPUT);//美化json字符串打印输出 } /** * 默认就有多种httpMessage消息序列化器,这里自定义json和xml转换器 * * @return CodecCustomizer 自定义转换器 */ @Bean @ConditionalOnBean(ObjectMapper.class) public CodecCustomizer jacksonCodecCustomizer(@Qualifier("jsonEncoder") Jackson2JsonEncoder jackson2JsonEncoder, Jackson2JsonDecoder jackson2JsonDecoder, CustomJaxb2XmlDecoder jaxb2XmlDecoder, @Qualifier("xmlEncoder") Jackson2JsonEncoder xmlEncoder) { return (configurer) -> { CodecConfigurer.DefaultCodecs defaults = configurer.defaultCodecs(); /* json反序列化器注册 */ defaults.jackson2JsonDecoder( jackson2JsonDecoder); /* json序列化器注册 */ defaults.jackson2JsonEncoder( jackson2JsonEncoder); final CodecConfigurer.CustomCodecs customCodecs = configurer.customCodecs(); /* xml序列化反序列化器注册 */ customCodecs.decoder(jaxb2XmlDecoder); customCodecs.encoder(xmlEncoder); }; } @Bean("jsonEncoder") public Jackson2JsonEncoder jackson2JsonEncoder(ObjectMapper objectMapper) { return new Jackson2JsonEncoder(objectMapper, this.jsonMimeTypes()); } @Bean public Jackson2JsonDecoder jackson2JsonDecoder(ObjectMapper objectMapper) { return new Jackson2JsonDecoder(objectMapper, this.jsonMimeTypes()); } @Bean public CustomJaxb2XmlDecoder jaxb2XmlDecoder() { return new CustomJaxb2XmlDecoder(this.xmlMimeTypes()); } @Bean("xmlEncoder") public Jackson2JsonEncoder xmlEncoder(XmlMapper xmlMapper) { return new Jackson2JsonEncoder(xmlMapper, this.xmlMimeTypes()); } private MimeType[] xmlMimeTypes() { return new MimeType[]{MimeTypeUtils.APPLICATION_XML, MimeTypeUtils.TEXT_HTML, MimeTypeUtils.TEXT_XML}; } private MimeType[] jsonMimeTypes() { return new MimeType[]{ new MimeType("application", "json", StandardCharsets.UTF_8), new MimeType("application", "*+json", StandardCharsets.UTF_8), MimeTypeUtils.TEXT_PLAIN }; } }
  • 在将配置应用到WebTestClient,只需修改DocsGen的setUp()方法:
    //注入上届的配置
    @Autowired
    private CodecCustomizer codecCustomizer;

    private WebTestClient webTestClient;


    @Before
    public void setUp() {
        final WebTestClient.Builder builder = WebTestClient.bindToApplicationContext(context)
                .configureClient();

        final SpringBootWebTestClientBuilderCustomizer builderCustomizer =
                new SpringBootWebTestClientBuilderCustomizer(Lists.newArrayList(codecCustomizer));
        //将自定义的序列化配置应用到webTestCliend
        builderCustomizer.customize(builder);

        this.webTestClient = builder.baseUrl("http://laprairie-enterprise.d.d1miao.com/")
                .filter(documentationConfiguration(restDocumentation))
                .build();
    }

重跑一边单元测试,查看上面的文件request-body.adoc,美化的json字符串好看多了。

[source,options="nowrap"]
----
{
  "username" : "admin",
  "password" : "12345"
}
----

3. 编写入口index.adoc和生成hmtl文件

上面生成了很多.adoc的文件,现在根据asciidoc德与法编写入口index文件。gradle项目在src目录下新建docs/asciidoc目录(maven项目在其他目录),然后新建两个文件如下图,后面跑完脚本会生成对应的html页面

login.adoc内容如下,主要是将build/generated-snippets下生成的文件导入进来

== *Backend user login:*

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

=== Request using HTTPie:

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

=== HTTP request:

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

=== Request body:

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

==== Request fields:

include::{snippets}/login/request-fields.adoc[]

=== HTTP response:

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

=== Response body:

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

==== Response fields:

include::{snippets}/login/response-fields.adoc[]

然后编写index.adoc文件,导入上面的login.adoc,如果还有其他adoc文件也可以都导入,按顺序编写导入

= XXX项目api文档
Jone Wang;
:toc: left ➊
:toc-title: 章节
:doctype: book
:icons: font
:source-highlighter: highlightjs

include::login.adoc[]

➊ 目录在左侧

现在执行gradle命令编译

./gradlew -Dorg.gradle.daemon=false -Dtest.enabled=true clean test asciidoctor bootJar

pc平台去掉最前面的’./” 因为我test.enabled默认配置未disable所以加了加了参数-Dtest.enabled=true

编译完毕后在build/asciiadoc/html5找到生成的html文件

用浏览器打开index.html看看,非常漂亮的api文档。

最后提示spring boot默认指定static为静态资源目录,如有修改需要重新配置gradle的bootJar,将into
改成自定义的目录

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

发表评论

电子邮件地址不会被公开。 必填项已用*标注