[Swagger] Swagger2Markup 配置

Swagger2Markup 配置

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

MAVEN

• MAVEN 依赖（代码生成）

    io.github.swagger2markup
    swagger2markup
    1.3.1

/*
 * @ProjectName: 编程学习
 * @Copyright:   2018 HangZhou Yiyuery Dev, Ltd. All Right Reserved.
 * @address:     http://xiazhaoyang.tech
 * @date:        2018/7/28 18:15
 * @email:       [email protected]
 * @description: 本内容仅限于编程技术学习使用，转发请注明出处.
 */
package com.xxx.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;

/**
 * 

 *
 * 
 *
 * @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 （插件生成）

 io.github.swagger2markup
 swagger2markup-maven-plugin
 1.3.3
 
     
     ${project.build.directory}/swagger-ui/swagger.yaml
     ${project.build.directory}/swagger-ui
     ${project.build.directory}/swagger-ui/swagger.md
     
         
         MARKDOWN
         
         TAGS
     
 
 
     
         compile
         
             convertSwagger2markup
         
     
 

配置项

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

---

更多

扫码关注“架构探险之道”，获取更多源码和文章资源

知识星球(扫码加入获取源码和文章资源链接)

---

评论回复

qq_36248731:

1、定义一个数据结构中含有Map,但是生成的html文档中并不是DTO链接

解决方法：

 @ApiModelProperty(value = "测试DTO",dataType = "java.util.Map",example = "10")
    private Map<String,PersonDetailDTO> result;