swagger离线文档导出html（maven插件版）

 

目录

一  前言

1、swagger作为出色的在线api生成工具，在项目中经常作为前后端接口对接的利器。

2、本文不阐述swagger及其配置，重点阐述如何导出swagger文档，无需代码编写。

二 实现

1、maven插件配置

2、配置结果 

3、配置详解

4、使用流程

5、项目github https://github.com/HandsomeMars/swagger-static-api-demo.git

三 参考

https://github.com/asciidoctor/asciidoctor-maven-examples

https://asciidoctor.org/docs/asciidoctor-maven-plugin/

http://swagger2markup.github.io/swagger2markup/1.3.1/

https://github.com/Swagger2Markup/spring-swagger2markup-demo

---

一  前言

1、swagger作为出色的在线api生成工具，在项目中经常作为前后端接口对接的利器。

但是：

• 线上的swagger是不安全的，使用不当会导致垃圾数据、是行走的bug和入侵渠道等。
• 前后端接口文档意在规约与分工，不适宜完全开发swagger代替接口文档
• 但是后期不管是后端接口测试还是前端接口对接实测，又需要维护swagger与接口文档

所以：基于swagger与接口文档同时维护这个需求，有折中方案：

• 写好swagger接口（定义接口与输入输出），导出离线文档
• 前后端同时开发，最后完成联调
• 如果接口变化，则重新导出离线文档，达到swagger与接口文档同时维护

2、本文不阐述swagger及其配置，重点阐述如何导出swagger文档，无需代码编写。

 

---

二 实现

1、maven插件配置

	io.github.swagger2markup
	swagger2markup-maven-plugin
	1.3.1
	
		
		http://ip:port/projectname/v2/api-docs
		
		${project.build.directory}/docs/asciidoc/swagger
		
		
			ZH
			true
			false
			TAGS
			ASCIIDOC
		
	


	org.asciidoctor
	asciidoctor-maven-plugin
	1.5.8
	
		
		${project.build.directory}/docs/asciidoc/
		
		${project.build.directory}/docs/html/
		
		html5
		coderay
		
			
			left
			
			3
			
			true
		
	

2、配置结果 

3、配置详解

• swagger2markup配置详解

（常用配置）

swagger2markup.markupLanguage=ASCIIDOC       ##MarkDown or ASCIIDOC  
swagger2markup.generatedExamplesEnabled=ture ##是否生成输入输出样例
swagger2markup.outputLanguage=ZH             ##文档输出语言  ZH中文
swagger2markup.inlineSchemaEnabled=false     ##是否启用参数内联
swagger2markup.pathsGroupedBy=TAGS           ##api排序规则  一般用tags排序

（参考官方api）

http://swagger2markup.github.io/swagger2markup/1.3.3/#_swagger2markup_properties

表1.最常用的属性

名称	描述	可能的值	默认
swagger2markup.markupLanguage	指定应用于生成文件的标记语言。	ASCIIDOC，MARKDOWN，CONFLUENCE_MARKUP	ASCIIDOC
swagger2markup.swaggerMarkupLanguage	指定Swagger描述中使用的标记语言。	ASCIIDOC，MARKDOWN，CONFLUENCE_MARKUP	降价
swagger2markup.pathsGroupedBy	指定路径的分组方式	AS_IS，TAGS，REGEX	AS_IS
swagger2markup.outputLanguage	指定标签的语言	EN，DE，FR，RU	EN
swagger2markup.lineSeparator	指定应使用的行分隔符	UNIX，WINDOWS，MAC	<系统依赖>
swagger2markup.generatedExamplesEnabled	指定是否应生成HTTP请求和响应示例	真假	假
swagger2markup.flatBodyEnabled	可选地将body参数（如果有）与其他参数隔离	真假	假
swagger2markup.pathSecuritySectionEnabled	（可选）禁用路径部分的安全性部分	真假	真正
swagger2markup.anchorPrefix	如果要将生成的文档包含在全局文档中，可以选择为所有锚点添加前缀以获得唯一性	任何字符串
swagger2markup.basePathPrefixEnabled	将basePath添加到所有路径	真假	假
swagger2markup.headerRegex	RegEx分组时使用的正则表达式	具有至少一个捕获组的任何有效RegEx模式

表2.配置Swagger对象顺序的属性

名称	描述	可能的值	默认
swagger2markup.tagOrderBy	指定全局标记的顺序	AS_IS，NATURAL，CUSTOM	自然
swagger2markup.operationOrderBy	指定路径操作的顺序	AS_IS，NATURAL，CUSTOM	自然
swagger2markup.definitionOrderBy	指定定义的顺序	AS_IS，NATURAL，CUSTOM	自然
swagger2markup.parameterOrderBy	指定操作参数的顺序	AS_IS，NATURAL，CUSTOM	自然
swagger2markup.propertyOrderBy	指定定义属性的顺序	AS_IS，NATURAL，CUSTOM	自然
swagger2markup.responseOrderBy	指定响应的顺序	AS_IS，NATURAL，CUSTOM	自然

表3.配置文档文件名的属性

名称	描述	可能的值	默认
swagger2markup.overviewDocument	指定概述文档的文件名	任何字符串	“概览”
swagger2markup.pathsDocument	指定路径文档的文件名	任何字符串	“路径”
swagger2markup.definitionsDocument	指定定义文档的文件名	任何字符串	“定义”
swagger2markup.securityDocument	指定安全文档的文件名	任何字符串	“安全”

表4.配置单独文件生成的属性

名称	描述	可能的值	默认
swagger2markup.separatedDefinitionsEnabled	除定义文件外，还为每个模型定义创建单独的定义文件	真假	假
swagger2markup.separatedOperationsEnabled	除Paths文件外，还为每个操作创建单独的操作文件	真假	假
swagger2markup.separatedOperationsFolder	指定定义文件的目标文件夹路径	任何有效的文件夹名称	“操作”
swagger2markup.separatedDefinitionsFolder	指定操作文件的目标文件夹路径	任何有效的文件夹名称	“定义”

表5.配置文档间交叉引用的属性

名称	描述	可能的值	默认
swagger2markup.interDocumentCrossReferencesEnabled	在需要时允许使用文档间交叉引用	真假	假
swagger2markup.interDocumentCrossReferencesPrefix	为高级用法指定所有文档间交叉引用的前缀	任何字符串

表6.配置内联架构呈现的属性

名称	描述	可能的值	默认
swagger2markup.inlineSchemaEnabled	启用内联对象架构支持	真假	真正

表7.配置分页符的属性

名称	描述	可能的值	默认
swagger2markup.pageBreakLocations	指定应插入分页符的位置。	BEFORE_OPERATION，BEFORE_OPERATION_DESCRIPTION，BEFORE_OPERATION_PARAMETERS，BEFORE_OPERATION_RESPONSES，BEFORE_OPERATION_CONSUMES，BEFORE_OPERATION_PRODUCES，BEFORE_OPERATION_EXAMPLE_REQUEST，BEFORE_OPERATION_EXAMPLE_RESPONSE，BEFORE_DEFINITION，AFTER_OPERATION，AFTER_OPERATION_DESCRIPTION，AFTER_OPERATION_PARAMETERS，AFTER_OPERATION_RESPONSES，AFTER_OPERATION_CONSUMES，AFTER_OPERATION_PRODUCES，AFTER_OPERATION_EXAMPLE_REQUEST，AFTER_OPERATION_EXAMPLE_RESPONSE，AFTER_DEFINITION	空

• asciidoctor配置详解

（常用配置）

#需要转换的asciidoc文件位置
sourceDirectory ${project.build.directory}/docs/asciidoc/
#需要转换后的文件输出位置
outputDirectory ${project.build.directory}/docs/html/
#转换使用的模板
backend html5、html
#模板主题
sourceHighlighter coderay

#其他配置属性
attributes
#导航栏在左#
toc left
#显示层级数
toclevels 3
#自动打数字序号
sectnums true
		、

（官方api配置） 

https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/master/README.adoc 

4、使用流程

 

•  双击swagger2mark插件生成adoc

• 双击 asciidoctor插件生成html

5、项目github https://github.com/HandsomeMars/swagger-static-api-demo.git

https://github.com/HandsomeMars/swagger-static-api-demo.git

 

---

三 参考

https://github.com/asciidoctor/asciidoctor-maven-examples

https://asciidoctor.org/docs/asciidoctor-maven-plugin/

http://swagger2markup.github.io/swagger2markup/1.3.1/

https://github.com/Swagger2Markup/spring-swagger2markup-demo