记录备忘
依赖配置
buildscript {
repositories {
maven { url "https://maven.aliyun.com/repository/gradle-plugin" }
maven { url "https://maven.aliyun.com/repository/public" }
mavenCentral()
}
dependencies {
...
classpath("org.asciidoctor:asciidoctor-gradle-jvm:3.3.2")
}
}
...
apply plugin: "org.asciidoctor.jvm.convert"
...
asciidoctor {
sourceDir file('src/docs') //接口描述文件读取目录
outputDir file('build/docs') //接口文档文件生成目录
asciidoctorj {
attribute("toc", "left")
attribute("toclevels", "3")
attribute("sectnums", true)
}
}
dependencies {
...
// swagger2
def swagger_version = "2.9.2"
implementation("io.springfox:springfox-swagger2:${swagger_version}")
implementation("io.springfox:springfox-swagger-ui:${swagger_version}")
// 通过跑测试程序来生成接口描述文件,所以只需要添加测试依赖即可
testImplementation("io.github.swagger2markup:swagger2markup:1.3.3")
}
原理流程
asciidoctor 是将一些标记类语言(比如markdown(.md),asciidoc(.adoc)) 的文本文件生成 html的一个库,那么我们要做的其实就是将 swagger 的接口描述信息转换成对应的文件即可, 这中间就是利用到了 swagger 自身的接口和 swagger2markup 这个库用来将接口信息转成对应的文件 .adoc ,然后利用 asciidoctor (构建插件会生成同名的gradle task) 最后生成html文档,最后利用chrome的打印功能生成pdf
测试类代码
@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@AutoConfigureMockMvc
public class BaseTest {
@Resource
protected MockMvc mockMvc;
/**
* json 转 asciidoc , 生成文件路径是 asciidoc 自身配置的 (参考上面的依赖配置)
*/
@Test
public void createSpringFoxSwaggerJson() throws Exception {
System.out.println("============================= 开始生成接口ASCII文档 =============================");
//MediaType.APPLICATION_JSON没有对字符编码进行设置，采用默认值，MockHttpServletResponse默认字符编码为ISO-8859-1
MvcResult mvcResult = mockMvc.perform(MockMvcRequestBuilders.get("/v2/api-docs")
.accept(MediaType.APPLICATION_JSON_UTF8))
.andExpect(MockMvcResultMatchers.status().isOk())
.andReturn();
MockHttpServletResponse response = mvcResult.getResponse();
String swaggerJson = response.getContentAsString();
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.withOutputLanguage(Language.ZH)
.withPathsGroupedBy(GroupBy.TAGS)
.withGeneratedExamples()
.withoutInlineSchema()
.build();
Swagger2MarkupConverter.from(swaggerJson)
.withConfig(config)
.build()
.toFile(Paths.get("src/docs/asciidoc/generated/index"));
System.out.println("============================= 生成接口ASCII文档完成 =============================");
}
}
该测试运行完成之后会在 src/docs/asciidoc/generated/ 目录生成 index.adoc 文件
生成文档文件
./gradlew asciidoctor --info
执行完成之后在 build/docs (参考上面的配置) 目录生成最后的html静态资源文件
