Swagger离线接口文档生成总结

时间：2025-03-15 14:23:19

Swagger离线接口文档生成总结

前言

需求：项目使用spring boot，maven工程，需要使用swagger生成接口文档，格式为html。
在网上查了一些资料，大部分是使用swagger-ui，在线文档，不符合要求；小部分提到了离线文档生成，但是总觉得有点绕，结合实际的使用经验，输出总结一篇，供参考。

本文使用常见的生成流程，swagger json -> asciidoc -> html,下面说明使用过程的几个关键点。

关键点1： 生成swagger json

生成swagger json,需要曲线救国一下，要在单元测试中调用生成函数生成。 

@WebAppConfiguration
@RunWith()
//需要替换为你的工程中的applicaton类
//SwaggerConfig为swagger配置信息，详情如下
@SpringApplicationConfiguration(classes = {, })
public class Swagger2MarkupTest {
    @Autowired
    private WebApplicationContext context;
    private MockMvc mockMvc;

    @Before
    public void setUp() {
         = ().build();
    }

    @Test
    public void convertSwaggerToAsciiDoc() throws Exception {
        (get("/v2/api-docs")
            .accept(MediaType.APPLICATION_JSON))
            .andDo(Swagger2MarkupResultHandler
                .outputDirectory("src/docs/asciidoc/generated").build())
            .andExpect(status().isOk());
    }
}

SwaggerConfig类主要配置需要扫描的接口信息，也放在单元测试的目录下。

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现
     *
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //package包名替换为你的工程中需要扫描的接口的包名
                .apis(("*.*.*.controller"))
                .paths(())
                .build();
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XX在线接口文档")
                .version("1.0")
                .build();
    }
}

这一步依赖的jar包如下：

    <!--主要用于函数和类的解释说明，swagger会扫描注解，生成对应信息-->
    <!--如果不需要更多说明，该jar包可以移除-->
    <dependency>
        <groupId></groupId>
        <artifactId>swagger-annotations</artifactId>
        <version>1.5.19</version>
    </dependency>

    <dependency>
        <groupId></groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.7.0</version>
        <scope>test</scope>
    </dependency>

    <dependency>
        <groupId></groupId>
        <artifactId>spring-restdocs-mockmvc</artifactId>
        <version>1.1.</version>
        <scope>test</scope>
    </dependency>

完成上述这几步，运行测试，就会生成对应的swagger json文件。

关键点2:生成ascii doc

该步骤主要使用swagger2markup-maven-plugin来生成（gradle工程有对应的gradle plugin），pom配置如下： 

<plugin>
            <groupId>.swagger2markup</groupId>
            <artifactId>swagger2markup-maven-plugin</artifactId>
            <version>${}</version>
            <dependencies>
                <dependency>
                    <groupId>.swagger2markup</groupId>
                    <artifactId>swagger2markup-import-files-ext</artifactId>
                    <version>${}</version>
                </dependency>
                <dependency>
                    <groupId>.swagger2markup</groupId>
                    <artifactId>swagger2markup</artifactId>
                    <version>${}</version>
                </dependency>
            </dependencies>
            <configuration>
                <!--swagger json路径-->
                <swaggerInput>${}</swaggerInput>
                <!--ascii doc输出目录-->
                <outputDir>${}</outputDir>
                <config>
                    <>ASCIIDOC</>
                    <>TAGS</>
                    <>${}/src/docs/asciidoc/extensions/overview</>
                    <>${}/src/docs/asciidoc/extensions/definitions</>
                    <>${}/src/docs/asciidoc/extensions/paths</>
                    <>${}src/docs/asciidoc/extensions/security</>
                </config>
            </configuration>
            <executions>
                <execution>
                    <phase>generate-sources</phase>
                    <goals>
                        <goal>convertSwagger2markup</goal>
                    </goals>
                </execution>
            </executions>
 </plugin>

相关配置信息:

<properties>
    <>1.3.1</>
    <>1.3.3</>
    <>1.3.1</>

    <>1.5.5</>
    <>1.5.0-alpha.15</>
    <>9.1.8.0</>

    <!--swagger json路径，在convertSwaggerToAsciiDoc中指定,替换成自己工程中的路径-->
    <>${}/src/docs/asciidoc/generated/</>
    <!--assiidoc使用的输入目录，adoc文件所在路径-->
    <>${}/src/docs/asciidoc</>
    <!--assiidoc输出目录-->
    <>${}/asciidoc</>
    <!--html文件输出目录-->
    <>${}/asciidoc/html</>
    <!--pdf文件输出目录-->
    <>${}/asciidoc/pdf</>
</properties>

关键点3：生成html或其它类型文件

该步骤使用assiidoc来将ascii doc文件转换为html或其它类型文件。 

<plugin>
            <groupId></groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>1.5.5</version>

            <dependencies>
                <!-- 生成pdf文件的jar包依赖。（如果不需要可以移除） -->
                <dependency>
                    <groupId></groupId>
                    <artifactId>asciidoctorj-pdf</artifactId>
                    <version>${}</version>
                </dependency>

                <!-- Comment this section to use the default jruby artifact provided by the plugin -->
                <dependency>
                    <groupId></groupId>
                    <artifactId>jruby-complete</artifactId>
                    <version>${}</version>
                </dependency>
                <!-- Comment this section to use the default AsciidoctorJ artifact provided by the plugin -->
                <dependency>
                    <groupId></groupId>
                    <artifactId>asciidoctorj</artifactId>
                    <version>${}</version>
                </dependency>
            </dependencies>

            <configuration>
                <!-- asciidoc输入目录,该目录用于存放adoc文件，我的理解是生成文档的框架文件，用于描述文档结构的-->
                <sourceDirectory>${}</sourceDirectory>
                <!--指定adoc文件名-->
                <sourceDocumentName></sourceDocumentName>
                <attributes>
                    <doctype>book</doctype>
                    <toc>left</toc>
                    <toclevels>3</toclevels>
                    <numbered></numbered>
                    <hardbreaks></hardbreaks>
                    <sectlinks></sectlinks>
                    <sectanchors></sectanchors>
                    <!--ascii doc文件所在路径，步骤2中的输出目录-->
                    <generated>${}</generated>
                </attributes>
            </configuration>

            <executions>
                <!-- 生成html文件 -->
                <execution>
                    <id>output-html</id>
                    <phase>generate-resources</phase>
                    <goals>
                        <goal>process-asciidoc</goal>
                    </goals>
                    <configuration>
                        <backend>html5</backend>
                        <!--html输出目录-->
                        <outputDirectory>${}</outputDirectory>
                    </configuration>
                </execution>
                <!-- 生成pdf文件.(如果不需要可以移除） -->
                <execution>
                    <id>output-pdf</id>
                    <phase>generate-resources</phase>
                    <goals>
                        <goal>process-asciidoc</goal>
                    </goals>
                    <configuration>
                        <backend>pdf</backend>
                        <!-- pdf文件输出目录-->
                        <outputDirectory>${}</outputDirectory>
                    </configuration>
                </execution>
            </executions>
 </plugin>

的内容: 

include::{generated}/[]
include::{generated}/[]
include::{generated}/[]
include::{generated}/[]

ok,完成这三个步骤，运行mnv install命令，就可以生成出像样的接口文档了。

总结

在实际使用中，可以将文件转换的工作当做一个单独的工程，swager json文件生成只作为单元测试代码存在，这样整个工程真正需要打进jar包的只有swagger-annotations，对现有代码影响较小，功能也很独立。

参考文档:

[1] 从代码中生成接口文档的完整过程–Gradle工程实例
[2] 将Swagger文件转换为html文件的maven工程示例
[3] Swagger2Markup官方文档
[4] Swagger2离线文档：PDF和Html5格式
[6] Swagger+spring boot 转换为html,PDF文件等

相关文章