当前位置：首页 > news >正文

Spring Boot-Swagger离线文档(插件方式）

news 来源：原创 2025/5/21 9:05:13

Swagger2Markup简介

Swagger2Markup是Github上的一个开源项目。该项目主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用，比如：AsciiDoc、Markdown、Confluence。
项目主页：https://github.com/Swagger2Markup/swagger2markup

版本说明

JDK: 11.0.26
Spring Boot: 2.4.11
Swagger: 2.9.2
Apache Maven: 3.8.8

下载配置Apache Maven

下载Apache Maven 3.8.8

https://gitee.com/yangsunior/csdn-resources

更新配置文件settings.xml

<?xml version="1.0" encoding="UTF-8"?><settings xmlns="http://maven.apache.org/SETTINGS/1.2.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.2.0 https://maven.apache.org/xsd/settings-1.2.0.xsd"><localRepository>C:\Users\tester\.m2\repository</localRepository><mirrors><!-- mirror| Specifies a repository mirror site to use instead of a given repository. The repository that| this mirror serves has an ID that matches the mirrorOf element of this mirror. IDs are used| for inheritance and direct lookup purposes, and must be unique across the set of mirrors.|<mirror><id>mirrorId</id><mirrorOf>repositoryId</mirrorOf><name>Human Readable Name for this Mirror.</name><url>http://my.repository.com/repo/path</url></mirror>--><mirror><id>aliyunmaven</id><mirrorOf>*</mirrorOf><name>阿里云公共仓库</name><url>https://maven.aliyun.com/repository/public</url></mirror><mirror><id>nexus-aliyun</id><mirrorOf>central</mirrorOf><name>Nexus aliyun</name><url>http://maven.aliyun.com/nexus/content/groups/public</url></mirror><mirror><id>nexus</id><name>internal nexus repository</name><url>http://repo.maven.apache.org/maven2</url><mirrorOf>central</mirrorOf></mirror></mirrors></settings>

设置依赖下载目录: C:\Users\tester.m2\repository
添加镜像仓库地址: 3个URL镜像地址

环境变量配置maven(可选)

Idea配置Maven

idea 配置 maven

pom.xml 引入依赖

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.4.11</version><relativePath/> <!-- lookup parent from repository --></parent><properties><swagger.version>2.9.2</swagger.version></properties><dependencies><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>${swagger.version}</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>${swagger.version}</version></dependency></dependencies><build><finalName>web-test-backend</finalName><plugins><plugin><groupId>io.github.swagger2markup</groupId><artifactId>swagger2markup-maven-plugin</artifactId><version>${swagger2markup.version}</version><configuration><swaggerInput>http://localhost:8081/v2/api-docs?group=dev-team</swaggerInput><outputDir>src/docs/asciidoc/generated</outputDir><config><!-- 生成asciidoc格式 --><swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage><!-- 生成markdown格式 --><!--<swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>--><swagger2markup.outputLanguage>ZH</swagger2markup.outputLanguage><swagger2markup.generatedExamplesEnabled>true</swagger2markup.generatedExamplesEnabled><swagger2markup.inlineSchemaEnabled>false</swagger2markup.inlineSchemaEnabled><swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy></config></configuration></plugin><plugin><groupId>org.asciidoctor</groupId><artifactId>asciidoctor-maven-plugin</artifactId><version>2.2.6</version><dependencies><dependency><groupId>org.asciidoctor</groupId><artifactId>asciidoctorj-pdf</artifactId><version>2.3.19</version></dependency><dependency><groupId>org.jruby</groupId><artifactId>jruby-complete</artifactId><version>9.4.5.0</version></dependency><dependency><groupId>org.asciidoctor</groupId><artifactId>asciidoctorj</artifactId><version>2.5.13</version></dependency></dependencies><configuration><sourceDirectory>src/docs/asciidoc/generated</sourceDirectory><attributes><toc>left</toc></attributes></configuration><executions><execution><id>output-html</id><phase>generate-resources</phase><goals><goal>process-asciidoc</goal></goals><configuration><backend>html5</backend><outputDirectory>src/docs/asciidoc/html</outputDirectory></configuration></execution><execution><id>generate-pdf-doc</id><phase>generate-resources</phase><goals><goal>process-asciidoc</goal></goals><configuration><backend>pdf</backend><outputDirectory>src/docs/asciidoc/pdf</outputDirectory><attributes><!--导航栏在左--><toc>left</toc><!--显示层级数--><toclevels>3</toclevels><numbered></numbered><hardbreaks></hardbreaks><sectlinks></sectlinks><sectanchors></sectanchors><generated>src/docs/asciidoc</generated><pdf-fontsdir>fonts</pdf-fontsdir><pdf-stylesdir>themes</pdf-stylesdir><pdf-style>cn-theme</pdf-style></attributes></configuration></execution></executions></plugin></plugins></build>
</project>

说明

swaggerInput：swagger生成的接口json数据文件。
输出：
- outputFile：输出到单一文件中
- outputDir：输出到指定文件中
swagger2markup.markupLanguage：输出格式
swagger2markup.outputLanguage：语言类型：如中文（ZH），默认英语（EN）
swagger2markup.generatedExamplesEnabled：指定是否应该生成HTTP请求和响应示例，默认false
swagger2markup.inlineSchemaEnabled：是否启用参数内联
swagger2markup.pathsGroupedBy：api排序规则一般用tags排序
executions：多个执行任务配置
execution.id：不可重复

其他：参考单独生成HTML与PDF相关说明

下载依赖

maven 同步

maven sync
Maven -> Sync Project，无法下载上述依赖，需要使用maven下载依赖。

package下载

maven package

下载字体与样式文件

font-theme
资源地址：https://gitee.com/yangsunior/csdn-resources/tree/master/20250519-swagger2markup

生成confluence

管理员模式打开命令行窗口，执行命令

> C:\WindowsApp\apache-maven-3.8.8\bin\mvn swagger2markup:convertSwagger2markup[INFO] Markup document written to: C:\Projects\web-test-backend\src\docs\asciidoc\generated\paths.adoc
[INFO] Markup document written to: C:\Projects\web-test-backend\src\docs\asciidoc\generated\definitions.adoc
[INFO] Markup document written to: C:\Projects\web-test-backend\src\docs\asciidoc\generated\security.adoc
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  3.551 s
[INFO] Finished at: 2025-05-20T16:03:19+08:00
[INFO] ------------------------------------------------------------------------

asciidoc-generated
运行之后就生成出了4个不同的静态文件

生成pdf/html

> C:\WindowsApp\apache-maven-3.8.8\bin\mvn generate-resources[INFO] Converted C:\Projects\web-test\backend\src\docs\asciidoc\generated\paths.adoc
[INFO] Converted C:\Projects\web-test\backend\src\docs\asciidoc\generated\security.adoc
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  01:35 min
[INFO] Finished at: 2025-05-20T16:24:30+08:00
[INFO] ------------------------------------------------------------------------

asciidoc-generated2
doc-html
doc-pdf pdf目录中的中文显示为乱码，暂时未解决。

多文件合并

修改outputDir为outputFile

<plugin><groupId>io.github.swagger2markup</groupId><artifactId>swagger2markup-maven-plugin</artifactId><version>${swagger2markup.version}</version><configuration><swaggerInput>http://localhost:8081/v2/api-docs?group=dev-team</swaggerInput><outputFile>src/docs/asciidoc/generated/all</outputFile><config><!-- 生成asciidoc格式 --><swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage><!-- 生成markdown格式 --><!--<swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>--><swagger2markup.outputLanguage>ZH</swagger2markup.outputLanguage><swagger2markup.generatedExamplesEnabled>true</swagger2markup.generatedExamplesEnabled><swagger2markup.inlineSchemaEnabled>false</swagger2markup.inlineSchemaEnabled><swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy></config></configuration>
</plugin>