引言

前后端分离的项目，接口文档的存在十分重要。与手动编写接口文档不同，swagger是一个自动生成接口文档的工具，只需要在pom文件中引入一个依赖包，然后在代码中通过注解的方式即可实现文档的编写，毕竟在需求不断变更的环境下，手动编写文档的效率实在太低且不够同步，swagger的出现，将文档和代码融合在一起，再也不需要写完代码后再去手动修改文档了。

简介

Swagger3在Swagger2的基础上进行了部分升级，与swagger2相比新版的swagger3配置更少，使用更加方便。

一个重要的优化是依赖的引入，由之前的多个依赖变更为一个依赖，跟随springboot-starter风格，同时引入了新的开关注解 @EnableOpenApi 以代替@EnableSwagger2 。

因此，集成工作变得更加的简便了，必要工作只有两个，添加swagger3的starter依赖包，在springboot主程序类添加@EnableOpenApi开关注解。

快速入门

引入依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

启动类添加开关注解@EnableOpenApi

作用：表示开启生成接口文档功能，只有开启了OpenApi，才能实现生成接口文档的功能

@EnableOpenApi
@SpringBootApplication
public class SwaggerApplication {

    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class, args);
    }

}

访问Swagger界面

访问地址（默认端口号是8080，各位根据实际情况修改即可）：http://localhost:8080/swagger-ui/index.html

进阶使用

配置Swagger

// 表明当前类是配置类
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                // 为api选择启动生成器
                .select()
                // 指定要生成api文档的根包
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 路径配置
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建一个ApiInfo对象
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 文档标题
                .title("SpringBoot整合Swagger3")
                // 简介
                .description("更多请咨询服务开发者小龍")
                // 作者信息：作者姓名、作者地址、作者邮箱
                .contact(new Contact("小龍", "https://blog.csdn.net/wangzhilong1996", "123456@qq.com"))
                // 版本号
                .version("1.0")
                .build();
    }
}

引入第三方UI包

原生的ui页面并不美观，我们可以选择使用第三方的ui包来美化页面，当然，市面上的第三方ui包有很多，大家可以找一个自己喜欢的，不一定用我的。

<!-- swagger 第三方ui包 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

访问地址：http://localhost:8080/doc.html

结语

以上是本人整理的一点关于swagger3.0的学习笔记，由于时间紧迫，文章中存在许多漏洞，希望各位能够批评指正，另外，还有两个遗留问题请教各位：

1、@EnableOpenApi注解到底是什么作用，尝试不加该注解，仍谈可以正常生成文档

2、如何在项目中实现不将swagger应用到生产环境中去
更多有关Springfox相关规范请参考：http://springfox.github.io/springfox/docs/current/

本文章会不定期更新，争取吃透swagger，欢迎各位关注，一起进步，共同成长。

原文链接：https://blog.csdn.net/wangzhilong1996/article/details/122575915