Swagger2Markup 配置

网上很多关于Swagger静态文档的生成大多缺少关于Swagger2Markup的配置项介绍，导致生成的静态文档可能连出入参JSON格式的示例都没有，本文主要是针对这个问题提出解决方案。

MAVEN

• MAVEN 依赖（代码生成）

<dependency>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup</artifactId>
    <version>1.3.1</version>
</dependency>

/*
 * @ProjectName: 编程学习
 * @Copyright:   2018 HangZhou Yiyuery Dev, Ltd. All Right Reserved.
 * @address:     http://xiazhaoyang.tech
 * @date:        2018/7/28 18:15
 * @email:       xiazhaoyang@live.com
 * @description: 本内容仅限于编程技术学习使用，转发请注明出处.
 */
package com.hikvision.cms.acs.web.test;

import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import org.apache.commons.configuration2.Configuration;
import org.apache.commons.configuration2.PropertiesConfiguration;

import java.net.URL;
import java.nio.file.Path;
import java.nio.file.Paths;

/**
 * <p>
 *
 * </p>
 *
 * @author xiachaoyang
 * @version V1.0
 * @date 2018年08月21日 9:45
 * @modificationHistory=========================逻辑或功能性重大变更记录
 * @modify By: {修改人} 2018年08月21日
 * @modify reason: {方法名}:{原因}
 * ...
 */
public class Swagger2Markup {

    //指定adoc文件生成路径
    private static Path outputDirectory;

    //通过配置文件生成swagger2markup的参数
    public Swagger2MarkupConfig config;

    public Swagger2Markup(String Json) throws Exception {
        //读取配置文件
        Configuration configuration = new PropertiesConfiguration();
        //设置输出文件的语言：ASCIIDOC, MARKDOWN, CONFLUENCE_MARKUP
        configuration.addProperty("swagger2markup.markupLanguage","ASCIIDOC");
        //设置目录的展现方式: AS_IS, TAGS
        configuration.addProperty("swagger2markup.pathsGroupedBy","TAGS");
        //是否输出request示例和response示例
        configuration.addProperty("swagger2markup.generatedExamplesEnabled",true);
        //输出文件的展示语言 ZH, EN, RU, FR, DE, TR, ES, BR, JA
        configuration.addProperty("swagger2markup.outputLanguage","EN");
        config = new Swagger2MarkupConfigBuilder(configuration).build();
        if (Json.startsWith("http")) {
            //获取远程json数据
            createAdocFile(new URL(Json));
        } else {
            //获取本地json数据
            createAdocFile(Paths.get(Json));
        }
    }

    /**
     * 循环生成json对应的acdoc
     * 指定远程json文件路径 new Swagger2Markup("http://petstore.swagger.io/v2/swagger.json");
     * - 执行main方法生成下方路径路径需要改为acs-web/target/.....
     * @throws Exception
     */
    public static void createAsciidoc(String outputDir, String resourceDir, String[] restFileNames) throws Exception {
        for (String fileName : restFileNames) {
            outputDirectory = Paths.get(outputDir  + fileName.replace(".json",""));
            //指定本地json文件路径
            new Swagger2Markup(resourceDir + fileName);
        }
    }

    /**
     * 通过url生成adoc文件
     *
     * @param remoteSwaggerFile
     */
    public void createAdocFile(URL remoteSwaggerFile) {
        Swagger2MarkupConverter.from(remoteSwaggerFile)
                .withConfig(config)
                .build()
                .toFolder(outputDirectory);
    }

    /**
     * 通过json文件生成adoc文件
     *
     * @param localSwaggerFile
     */
    public void createAdocFile(Path localSwaggerFile) {
        Swagger2MarkupConverter.from(localSwaggerFile)
                .withConfig(config)
                .build()
                .toFolder(outputDirectory);
    }

    public static void main(String[] args) throws Exception {
        //createAsciidoc("acs-web/target/asciidoc/generated/","acs-web/target/swagger/",new String[]{"acs-ui-v1.json","acs-api-v1.json"});
    }
}

• MAVEN PLUGIN （插件生成）

<plugin>
 <groupId>io.github.swagger2markup</groupId>
 <artifactId>swagger2markup-maven-plugin</artifactId>
 <version>1.3.3</version>
 <configuration>
     <!--The URL or file path to the Swagger specification-->
     <swaggerInput>${project.build.directory}/swagger-ui/swagger.yaml</swaggerInput>
     <outputDir>${project.build.directory}/swagger-ui</outputDir>
     <outputFile>${project.build.directory}/swagger-ui/swagger.md</outputFile>
     <config>
         <!--设置输出文件的语言：ASCIIDOC, MARKDOWN, CONFLUENCE_MARKUP-->
         <swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>
         <!--设置目录的展现方式-->
         <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
     </config>
 </configuration>
 <executions>
     <execution>
         <phase>compile</phase>
         <goals>
             <goal>convertSwagger2markup</goal>
         </goals>
     </execution>
 </executions>
</plugin>

配置项

maven jar

swagger2markup.markupLanguage=ASCIIDOC
swagger2markup.swaggerMarkupLanguage=MARKDOWN
swagger2markup.generatedExamplesEnabled=false
swagger2markup.basePathPrefixEnabled=false
swagger2markup.operationExtensionsEnabled=false
swagger2markup.definitionExtensionsEnabled=false
swagger2markup.separatedDefinitionsEnabled=false
swagger2markup.separatedOperationsEnabled=false
swagger2markup.pathsGroupedBy=AS_IS
swagger2markup.outputLanguage=EN
swagger2markup.inlineSchemaEnabled=true
swagger2markup.interDocumentCrossReferencesEnabled=false
swagger2markup.flatBodyEnabled=false
swagger2markup.pathSecuritySectionEnabled=true
swagger2markup.overviewDocument=overview
swagger2markup.pathsDocument=paths
swagger2markup.definitionsDocument=definitions
swagger2markup.securityDocument=security
swagger2markup.separatedOperationsFolder=operations
swagger2markup.separatedDefinitionsFolder=definitions
swagger2markup.tagOrderBy=NATURAL
swagger2markup.operationOrderBy=NATURAL
swagger2markup.definitionOrderBy=NATURAL
swagger2markup.parameterOrderBy=NATURAL
swagger2markup.propertyOrderBy=NATURAL
swagger2markup.responseOrderBy=NATURAL
swagger2markup.listDelimiterEnabled=false
swagger2markup.listDelimiter=,

配置项说明

配置说明

JSON报文展示：

输入图片说明

REFRENCES

1. 使用swagger2markup和asciidoctor生成美观的Restful API文档
2. Swagger2Markup Documentation

---

更多

架构探险之道

扫码关注或搜索架构探险之道获取最新文章，不积跬步无以至千里，坚持每周一更，坚持技术分享^_ ！