swagger3 离线文档 笔记

本文章仅作为个人笔记

官方网站 / 参考文档 / 官方项目 / 个人 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用于参考

©️2020 CSDN 皮肤主题: 大白 设计师:CSDN官方博客 返回首页