springboot整合swagger（api集成、转word、离线文档）

网络上有许多零零散散的swagger相关使用说明，这里整合如下参考内容及个人过程中发现和解决的相关问题：

1.相关pom依赖【注意点：不同版本swagger-ui不同，依赖包版本不同会出现类似方法找不到，包依赖报错问题】

        <!--springfox-version对应使用的是-2.6.1-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox-version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${springfox-version}</version>
        </dependency>
        <!--之前报错缺失，特意增加-->
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>28.0-jre</version>
        </dependency>

        <!--swagger静态化输出依赖-->
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.3</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/ch.netzwerg/paleo-core -->
        <dependency>
            <groupId>ch.netzwerg</groupId>
            <artifactId>paleo-core</artifactId>
            <version>0.11.0</version>
        </dependency>
        <dependency>
            <groupId>nl.jworks.markdown_to_asciidoc</groupId>
            <artifactId>markdown_to_asciidoc</artifactId>
            <version>1.0</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.swagger/swagger-core -->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-core</artifactId>
            <version>1.5.21</version>
        </dependency>

        <!-- https://mvnrepository.com/artifact/io.swagger/swagger-models -->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.21</version>
        </dependency>

2.swaggerConfig-配置文件：

@EnableSwagger2--可加在启动类上看个人使用

/**
 * @author ：hw
 * @date ：Created in 2021/6/10
 * @modified By：
 * @version: 1.0.0
 */
@Configuration
@EnableSwagger2
//@Profile({"2"})---设置环境对应使用权限
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否开启 (true 开启  false隐藏。生产环境建议隐藏)
                //.enable(false)
                .select()
                //扫描的路径包,设置basePackage会将包下的所有被@Api标记类的所有方法作为api
                .apis(RequestHandlerSelectors.basePackage("org.word.controller"))
                //指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //设置文档标题(API名称)
                .title("SpringBoot-Swagger2")
                //文档描述
                .description("接口说明")
                //服务条款URL
                .termsOfServiceUrl("http://localhost:8080/")
                //版本号
                .version("1.0.0")
                .build();
    }


}

3.项目启动，访问swagger-UI对应界面：http://localhost:8080/swagger-ui.html

 

两个重要的URL：

UI访问：http://localhost:8080/swagger-ui.html

 

对应文档：http://localhost:8080/v2/api-docs

可以替代直接使用报文或者对应的请求发起接口测试，如下图

4.生成对应的api文档，一定要保证pom依赖正确（上面pom文件已经包含）-关键依赖：

 <!--swagger静态化输出依赖-->
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.3</version>
        </dependency>

生成-直接run对应方法即可：

/**
 * @author ：hw
 * @date ：Created in 2021/6/10
 * @modified By：
 * @version: 1.0.0
 */
@RunWith(SpringRunner.class)
@SpringBootTest(classes = Application.class)
public class Swagger2MarkUpTest {
    /**
     * 生成Markdown格式文档,并汇总成一个文件
     *
     * @throws Exception
     */
    @Test
    public void generateMarkdownDocsToFile() throws Exception {
        //  输出Markdown到单文件
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("./docs/api"));
    }
}

5.swagger本身是不支持生成word文档，需要对应模板，将http://localhost:8080/v2/api-docs返回的api接口的相关信息json串转化成word文档；

这里提供：https://gitee.com/yellowill/SwaggerSpringBoot.git--参考

使用：

参考内容如下：

swagger-ui导出word接口文档_a116385895的博客-优快云博客

Swagger2生成接口文档_gaochenglong1的博客-优快云博客_swagger2生成接口文档

使用Swagger2Markup导出swagger2文档_qq_35140272的博客-优快云博客