从零学习Swagger3.0（最全讲解）

秒速五厘米 2022-09-11 02:18 461阅读 0赞

## 一、什么是Swagger？ ##

### 1、前言 ###

做为一个后端开发人员或者是前端开发人员，总归是要沟通调试项目的，前端要接口数据，不知道接口地址，我总不能一个一个的把接口地址发给他吧，前端可能要打人了，后端觉得编写及维护接口文档会耗费不少精力，所以双方经常抱怨，经常扯皮，有这时间摸摸鱼不好嘛，所以Swagger就来接手这个重任，将项目的接口进行管理。所以前端只需要这一份接口文档就可以拿到数据，进行数据的处理等。提高开发效率。

### 2、Swagger介绍 ###

官方网址：[Swagger官网][Swagger]

![image-20210909224710222][]

### 3、使用Swagger的好处 ###

*  **无依赖**
    
    UI 适用于任何开发环境，无论是本地还是 Web。
 *  **人性化**
    
    允许最终开发人员轻松交互并尝试您的 API 公开的每一个操作，以便于使用。
 *  **易于导航**
    
    使用分类整齐的文档快速查找和使用资源和端点。
 *  **所有浏览器支持**
    
    通过适用于所有主要浏览器的 Swagger UI 迎合所有可能的场景。
 *  **完全可定制的**
    
    样式并通过完整的源代码访问以您想要的方式调整您的 Swagger UI。
 *  **完整的 OAS 支持**
    
    可视化 Swagger 2.0 或 OAS 3.0 中定义的 API。

## 二、项目中如何载入Swagger？ ##

说到这，有人会问，该如何把Swagger引用到项目中呢，不会是YY意想的吧，肯定不是，只需要导个包就可以了。有人又问：在哪导包，导什么包？

我来告诉你，就在项目的pom.xml中，复制粘贴以下代码，就完成了Swagger加载到项目中了。

![image-20210910202309687][]

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>

添加完，等待下载完包即可。此时Swagger已经加入了项目中。

## 三、如何使用Swagger？ ##

准备工作结束啦，那如何使用呢？是啊，如何使用啊，有人说：接口文档肯定要在接口使用，我转身给你一个大大的赞，说的太对了，最主要的作用就是在接口上使用。接下来跟我来学习如何使用。

### 1、接口归类 ###

首先我们在Controller类上加入一个Swagger注解：`@Api`主要是描述这个Controller是哪一个模块的接口，分类明确。假如是用户的接口类。那么这个类会有对用户的增删改查不同的方法。

![image-20210910203518196][]

@RestController
    @Api(tags = "图书管理") //每个Controller上加上一个@Api注解
    public class LibraryController { 
    
        @Autowired
        BookService bookService;
    }

### 2、接口方法 ###

大的分类标注好了，下面则是每个接口方法的标题，我们在每个方法的上面添加一个`@ApiOperation`注解，描述这个接口方法的功能，是删除还是修改或者添加等。

![image-20210910211037668][]

@RestController
    @Api(tags = "图书管理")
    public class LibraryController { 
    
        @Autowired
        BookService bookService;
    
        @GetMapping("/api/books")
        @ApiOperation(value = "图书列表")
        public List<Book> list() throws Exception { 
            return bookService.list();
        }
    }

到此，你以为就这样好了吗？没错，这就好了，此时我们启动项目，一般项目都是localhost:8080地址，然后加上Swagger的路径。

点击http://localhost:8080/swagger-ui/index.html则会出现以下界面。

![image-20210910215551556][]

看到了吧，有我刚才加的接口标签。此时Swagger添加好了，就可以正常的使用了。

## 四、配置Swagger ##

以上的步骤Swagger可以用了，但是为了项目的规范化，我们可以对这个页面进行改造，版本、指定controller包等操作。

我们在项目中新建一个util工具包，然后新建一个Swagger配置类。

![image-20210910221939147][]

先上代码：

package com.demo.book.util;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.oas.annotations.EnableOpenApi;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Contact;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    
    @Configuration
    @EnableOpenApi
    public class Swagger3Config { 
    
        @Bean
        public Docket docket(){ 
            return new Docket(DocumentationType.OAS_30)
                    .apiInfo(apiInfo()).enable(true)
                    .select()
                    //添加swagger接口提取范围,修改成指向你的controller包
                    .apis(RequestHandlerSelectors.basePackage("com.demo.book.controller"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo(){ 
            return new ApiInfoBuilder()
                    .title("图书管理系统接口文档")
                    .description("这是一个图书管理系统")
                    .contact(new Contact("码上言", "www.xyhwh.cn", "作者Email"))
                    .version("1.0")
                    .build();
        }
    
    }

配置完，重启项目，效果如下：

![image-20210910222230356][]

**注：如果你不指向你的controller包，则页面上就不会有接口显示，如下图所示**

![image-20210910222509700][]

好啦，到此就是Swagger3.0全部的讲解，原创不易，各位小伙伴给个赞！

有什么问题欢迎和我交流。或者关注我的微信公众号\*\*“*码上言*”\*\*获得更多的学习。

![微信公众号：码上言][26e793d93499cb2c2afa75ea987e42a3.png]

[Swagger]: https://swagger.io/
[image-20210909224710222]: /images/20220829/6e4dbaf018524135a1832d405f350fcb.png
[image-20210910202309687]: /images/20220829/74dcde6d23d642db8fe8123ac54d6e71.png
[image-20210910203518196]: /images/20220829/afba11e412ac4de7bc586d3000b1b97a.png
[image-20210910211037668]: /images/20220829/4235ec0f372d45c69823467be113bc6f.png
[image-20210910215551556]: /images/20220829/8772f951e4af46fc8180593a4ca7c7b9.png
[image-20210910221939147]: /images/20220829/a9a909de2f1a4cd08b8923bd4b1d217f.png
[image-20210910222230356]: /images/20220829/54df4fc6b22f4675a0d3a4a5c1f3c6cd.png
[image-20210910222509700]: /images/20220829/cc41cc1e4c4d4663be0ed785d22ee14a.png
[26e793d93499cb2c2afa75ea987e42a3.png]: /images/20220829/31b6e1e555524a5cab832f6712530b0a.png