swagger2markup 将swaggerAPI转换成md文档->转换成html文档

添加依赖(POM.XML)

     org.asciidoctor
     asciidoctorj
     2.1.0
 
 
 
     io.github.swagger2markup
     swagger2markup
     1.3.3
 
 
   
       
           true
           always
       
       jcenter-snapshots
       jcenter
       http://oss.jfrog.org/artifactory/oss-snapshot-local/
   
   
       
           true
           always
       
       jcenter-releases
       jcenter
       http://jcenter.bintray.com
   

实例展示

/**
     * swagger api转成　adoc  文件
     *
     * @param apiUrl       swagger 文档的访问路径
     *                     例如:/v2/api-docs?group=registercompany
     * @param adocFilePath 生成的adoc文件保存路径
     *                     例如: asciidoc\generated
     *                     返回值: 会在该路径下看到 asciidoc\generated.adoc文件
     * @return boolean 创建结果
     * @throws Exception 创建失败抛出异常
     */
    public static boolean swaggerApiToAdoc(String apiUrl, String adocFilePath) throws Exception {
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC) // 此处修改为 MarkupLanguage.MARKDOWN  即可生成md文档
                .withPathsGroupedBy(GroupBy.TAGS)
                .withOutputLanguage(Language.ZH)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();
        Swagger2MarkupConverter.Builder from =
                Swagger2MarkupConverter.from(new URL(apiUrl));
        Swagger2MarkupConverter.Builder builder = from.withConfig(config);
        Swagger2MarkupConverter build = builder.build();
        if (adocFilePath.endsWith(".adoc")) {
            adocFilePath = adocFilePath.substring(0, adocFilePath.length() - 5);
        }
        build.toFile(Paths.get(adocFilePath));
        return true;
    }

    public static boolean adocToHtml(String adocFilePath, String baseDir) {

        System.setProperty("jruby.compile.mode", "OFF");
        Asciidoctor asciidoctor = Asciidoctor.Factory.create();
        Options options = new Options();
        // 建立新的目录
        options.setMkDirs(true);
        // 保存到文件
        options.setToFile(true);
        // 设置安全等级
        options.setSafe(SafeMode.UNSAFE);
        // 生成html5
        options.setBackend("html5");
        // 属性配置
        HashMap attributes = new HashMap<>(2);
        // 左侧
        attributes.put(Attributes.TOC, Placement.LEFT.getPosition());
        // 设置目录 编号 编号等级
        attributes.put("toclevels", 4);
        attributes.put(Attributes.SECTION_NUMBERS, true);
        attributes.put(Attributes.SECT_NUM_LEVELS, 4);
        attributes.put(Attributes.TITLE, "apiWendang");

        options.setAttributes(attributes);
        options.setBaseDir(baseDir);
        asciidoctor.convertFile(new File(adocFilePath), options);
        return true;
    }

    public static void main(String[] args) throws Exception {
        String apiUrl = "http://192.168.18.200:10121/v2/api-docs?group=user";
        String adocFilePath = "\\docs\\asciidoc\\generated.adoc";
        String baseDir = "\\docs\\asciidoc";
        boolean createAdocFlag = swaggerApiToAdoc(apiUrl, adocFilePath);
        boolean adocToHtmlFlag = adocToHtml(adocFilePath, baseDir);
    }

最后

如果存在问题: 生成完成后浏览html文件,发现缺少样式

解决:

[idea]  ctrl shift n asciidoctor-default.css  
查找到该文件修改文件名为asciidoctor.css 放到baseDir下(和生成的html文件同级目录)

资源下载地址

参考博客

GITHUB https://github.com/asciidoctor/asciidoctorj/blob/305c1b3720/docs/integrator-guide.adoc
CSDN: https://blog.csdn.net/itliwei/article/details/84726386