如何通过Maven结合Swagger 2.x生成HTML文档？

我刚好在几个Jersey项目里实现过用Swagger生成静态HTML文档的需求，也对Swagger的常规用法比较熟悉，给你详细说说：

1. 通过Maven结合Swagger生成HTML文档的简易方案 #

核心思路是先让Swagger扫描你的Jersey API代码生成标准的swagger.json描述文件，再通过Maven插件把这个JSON转成静态HTML，全程不需要启动服务就能离线生成，步骤如下：

步骤1：添加必要的依赖和Maven插件 #

在你的pom.xml里加入Swagger与Jersey的集成依赖，以及两个关键Maven插件：

<!-- Swagger Jersey集成依赖，用于扫描API注解 -->
<dependencies>
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-jersey2-jaxrs</artifactId>
        <version>1.6.12</version> <!-- 选稳定的适配版本 -->
    </dependency>
</dependencies>

<!-- Maven插件1：扫描代码生成swagger.json -->
<build>
    <plugins>
        <plugin>
            <groupId>com.github.kongchen</groupId>
            <artifactId>swagger-maven-plugin</artifactId>
            <version>3.1.8</version>
            <configuration>
                <apiSources>
                    <apiSource>
                        <springmvc>false</springmvc> <!-- 因为是Jersey，禁用Spring MVC模式 -->
                        <locations>com.yourpackage.resources</locations> <!-- 替换成你的API资源类所在包 -->
                        <schemes>http</schemes>
                        <host>localhost:8080</host> <!-- 你的服务域名/端口 -->
                        <basePath>/api</basePath> <!-- API的基础路径 -->
                        <info>
                            <title>你的API文档标题</title>
                            <version>1.0.0</version>
                            <description>API功能描述</description>
                        </info>
                        <swaggerDirectory>${project.build.directory}/swagger</swaggerDirectory> <!-- swagger.json输出目录 -->
                    </apiSource>
                </apiSources>
            </configuration>
            <executions>
                <execution>
                    <phase>compile</phase>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>

        <!-- Maven插件2：把swagger.json转成静态HTML -->
        <plugin>
            <groupId>io.swagger.codegen.v3</groupId>
            <artifactId>swagger-codegen-maven-plugin</artifactId>
            <version>3.0.46</version>
            <executions>
                <execution>
                    <id>generate-html-docs</id>
                    <phase>package</phase>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                    <configuration>
                        <inputSpec>${project.build.directory}/swagger/swagger.json</inputSpec> <!-- 指向上面生成的JSON文件 -->
                        <output>${project.build.directory}/swagger-html</output> <!-- HTML文档输出目录 -->
                        <language>html</language> <!-- 指定生成HTML格式 -->
                        <configOptions>
                            <title>你的API文档标题</title>
                        </configOptions>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

步骤2：执行Maven命令生成文档 #

在项目根目录运行：

mvn clean package

执行完成后，你可以在target/swagger-html目录下找到生成的静态HTML文档，直接用浏览器打开就能查看。

2. REST应用中将文档与服务绑定是否属于常规做法？ #

这绝对是行业内的常规且推荐的实践，原因主要有几点：

• 实时同步：文档和服务一起部署，API接口有变更时，文档会自动同步更新，彻底避免“文档和实际API不一致”的尴尬问题
• 便捷调试：绑定服务的Swagger UI（比如访问/swagger-ui路径）不仅能查看文档，还能直接在线调用API进行调试，极大提升开发效率
• 统一入口：团队成员和外部使用者不需要额外查找文档地址，直接通过服务域名就能访问文档，降低沟通成本

当然，如果有离线文档的需求（比如给客户提供静态文档、部署到静态文件服务器），生成静态HTML是很好的补充方案，但日常开发和维护中，绑定服务的Swagger UI是首选方式。

内容的提问来源于stack exchange，提问作者user0000001