本文章仅作为个人笔记
官方网站 / 参考文档 / 官方项目 / 个人 demo
- wagger 的集成与静态文件生成 (在线/离线文档)
-
新建springboot项目并在build.gradle文件添加相关依赖
# 引用插件(不生成离线文档可以不引入) plugins { id 'org.asciidoctor.convert' version '2.3.0' id "io.github.lhotari.swagger2markup" version "1.3.3.1" } # 解决中文乱码问题 tasks.withType(JavaCompile) { options.deprecation = true options.encoding = 'UTF-8' options.compilerArgs << "-Xlint:unchecked" } # 设置仓库 repositories { jcenter() mavenCentral() } # 设置输出文件夹及swagger版本 ext { swaggerVersion = "3.0.0" swaggerOutputDir = file("${project.rootDir}/api/swagger") asciiDocOutputDir = file("${project.rootDir}/api/asciidoc") snippetsOutputDir = file("${project.rootDir}/api/snippets") } # 引用依赖 dependencies { // swagger3 依赖 implementation("io.springfox:springfox-boot-starter:${swaggerVersion}") // 离线文档生成 依赖(不生成离线文档可以不引入) implementation("io.github.swagger2markup:swagger2markup:1.3.3") // 测试 依赖(不生成离线文档可以不引入) testImplementation("org.springframework.boot:spring-boot-starter-test") testImplementation("org.springframework.restdocs:spring-restdocs-mockmvc") } # 设置全局离线文档输出地址 (不生成离线文档可以不设置) test { systemProperty 'io.springfox.staticdocs.outputDir', swaggerOutputDir systemProperty 'io.springfox.staticdocs.snippetsOutputDir', snippetsOutputDir # 构建时忽略 生成文件的测试 exclude '**/DemoApplicationTests.class' } # 添加离线文档转换task (不生成离线文档可以不设置) convertSwagger2markup { dependsOn test swaggerInput "${swaggerOutputDir}/swagger.json" outputDir asciiDocOutputDir config = [ 'swagger2markup.pathsGroupedBy' : 'TAGS', 'swagger2markup.extensions.springRestDocs.snippetBaseUri': snippetsOutputDir.getAbsolutePath()] } # 添加离线文档生成task (不生成离线文档可以不设置) asciidoctor { dependsOn convertSwagger2markup sourceDir = file("${swaggerOutputDir}") sources { include 'index.adoc' } backends = ['html5'] attributes = [ doctype : 'book', toc : 'left', toclevels : '3', numbered : '', sectlinks : '', sectanchors: '', hardbreaks : '', generated : swaggerOutputDir ] outputDir = swaggerOutputDir }
-
为项目添加 swagger 配置 开启swagger/设置swagger基本信息等
# 自定义swagger开关 在 application.yml 添加对应配置打开或者不设置便关闭 @Value("${swagger.enable:false}") private boolean swaggerEnable; @Bean public Docket createRestApi() { return new Docket(DocumentationType.OAS_30) .enable(swaggerEnable) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("图模服务") .version("1.0") .build(); }
-
为项目添加单元测试,用于生成静态 adoc/md/json 文件(不生成静态文件请忽略)
# 获取设置的静态文件生成路径 String outputDir = System.getProperty("io.springfox.staticdocs.outputDir"); # 根据api获取接口内容 MvcResult mvcResult = this.mockMvc .perform(get("/v2/api-docs") .accept(MediaType.APPLICATION_JSON)) .andExpect(status().isOk()) .andReturn(); MockHttpServletResponse response = mvcResult.getResponse(); response.setCharacterEncoding("utf-8"); String swaggerJson = response.getContentAsString(); Files.createDirectories(Paths.get(outputDir)); # 输出为 json 文件 try (BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir, "swagger.json"), StandardCharsets.UTF_8)) { writer.write(swaggerJson); } Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.ASCIIDOC) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); # 输出为 asciidoc 文件 Swagger2MarkupConverter.from(swaggerJson) .withConfig(config) .build() .toFile(Paths.get(outputDir + "/index")); config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.MARKDOWN) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); # 输出为 md 文件 Swagger2MarkupConverter.from(swaggerJson) .withConfig(config) .build() .toFile(Paths.get(outputDir + "/index"));
-
做好准备工作为相应的接口(api/controller)添加对应swagger注解 具体用法自行参考官方文档
-
最后运行
gradle build test gradle build asciidoctor
-
至此便完成了 swagger3 的集成与静态文件的生成
-
最后奉上个人demo用于参考
-