[Swagger] Swagger2Markup 配置
2024-06-30 04:06:07
目录
- Swagger2Markup 配置
- MAVEN
- 配置项
- REFRENCES
- 更多
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.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;/*** <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_MARKUPconfiguration.addProperty("swagger2markup.markupLanguage","ASCIIDOC");//设置目录的展现方式: AS_IS, TAGSconfiguration.addProperty("swagger2markup.pathsGroupedBy","TAGS");//是否输出request示例和response示例configuration.addProperty("swagger2markup.generatedExamplesEnabled",true);//输出文件的展示语言 ZH, EN, RU, FR, DE, TR, ES, BR, JAconfiguration.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>
配置项
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
- 使用swagger2markup和asciidoctor生成美观的Restful API文档
- Swagger2Markup Documentation
更多
扫码关注“架构探险之道”，获取更多源码和文章资源
知识星球(扫码加入获取源码和文章资源链接)
评论回复
qq_36248731:
1、定义一个数据结构中含有Map<String,MyDTO>,但是生成的html文档中并不是DTO链接
解决方法：
@ApiModelProperty(value = "测试DTO",dataType = "java.util.Map<java.lang.String,com.xxx.x.xx.x.x.x.PersonDetailDTO>",example = "10")private Map<String,PersonDetailDTO> result;
[Swagger] Swagger2Markup 配置相关推荐
- [Swagger] Asciidoc 配置静态章节
目录 Asciidoc 配置静态章节 MAVEN 静态章节配置 MAVAN命令切换输出方式 Asciidoc InteillJ IDEA Plugin REFRENCES 更多 Asciidoc 配置 ...
- Swagger中配置了@ApiModelProperty的allowableValues属性但不显示的问题
现在用Swagger来生成API文档的例子已经非常多了,今天碰到开发同事问了一个问题,帮着看了一下,主要还是配置方法的问题,所以记录一下.如果你也碰到了同样的问题,希望本文对您有用. 问题描述 @Ap ...
- 【Swagger】配置信息详解（涉及源码分析）
先来说说 Swagger 有什么用,相较于使用 markdown 或者 word 写接口文档,Swagger 自动生成 API 文档,然后在 web 端暴露,并且 API 文档与 API 定义同步更新 ...
- Swagger的配置教程（超级详细）
1.引入相关依赖 <!--swagger--> <dependency><groupId>io.springfox</groupId><artif ...
- Swagger UI 配置
层主用的环境是spring boot+swagger 用的shiro做的拦截 首先导入swagger ui依赖的jar包 <dependency><groupId>io.spr ...
- Swagger使用配置
目录 1:认识Swagger 2:Maven 3:创建Swagger2配置类 4:添加文档内容 5:Swagger UI面板说明 6:参考 7:接收对象传参的例子 1:认识Swagger Swagge ...
- swagger依赖配置
引入swagger依赖 <!--swagger--><dependency><groupId>io.springfox</groupId><art ...
- swagger访问开关配置
swagger Docket方法中有enable参数(类型为boolean,true表示开启swagger的访问,false表示关闭swagger的访问) import org.springframe ...
- swagger 配置- ssm
swagger 配置 - ssm swagger 是一个用来看接口的工具,具体效果如下,这里用的是swagger2 1.porm.xml <dependency><groupId&g ...
最新文章
- VMware虚拟机文件夹中各文件作用详解
- jquery插件编写学习
- 看不到这些痛点，就无法入局智能制造
- Java实现二树杈_HashSet的hashCode方法和equals方法的重写，TreeSet中compareTo方法的重写，Comparator在treeSet中的应用。...
- Python 数据分析三剑客之 Pandas（二）：Index 索引对象以及各种索引操作
- 服务器系统日志6008,DELL服务器宕机事件6008
- 搞不明白老板想要看哪种报表，熬夜做到两点也是白费28
- axios java 参数,vue.js axios发请求时,参数包括dto和一个flag, 后台如何接?
- tensorflow 2.X中构建模型的三种方式：Sequential, Functional, Subclassing
- C++实现11平台魔兽全图外挂
- 圈子论坛社区小程序,交友,博客,社交,陌生人社交,即时聊天 前后端开源PHP
- linux下通过V4L2驱动USB摄像头
- Helio for mac(音乐创作工具)
- 企业实战之部署Solarwinds Network八部众
- 无线渗透-----aircrack-ng破解WEP加密
- 拉丁超立方抽样的Python实现
- haar adaboost matlab,人脸检测算法之Haar-Adaboost分类器原理
- C++中string.size()函数 踩坑
- STL容器基础 - 0
- 舒亦梵：4.24非农周即将来临，作为投资者的你做好准备了吗