SpringBoot整合Swagger3.0全过程_Java

一、引言

前后端分离的项目，接口文档的存在十分重要。与手动编写接口文档不同，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