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

1年前 (2023) 程序员胖胖胖虎阿

113 0 0

一、什么是Swagger？

最近在扩展自己的新知识，然后发现了一个巨牛的人工智能学习网站，通俗易懂，风趣幽默，忍不住分享一下给大家。点击跳转到教程。
此文是想要进入人工智能这个领域、但不知道从哪里开始的初学者最佳的学习资源列表。

1、前言

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

2、Swagger介绍

官方网址：Swagger官网

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

3、使用Swagger的好处

无依赖

UI 适用于任何开发环境，无论是本地还是 Web。
人性化

允许最终开发人员轻松交互并尝试您的 API 公开的每一个操作，以便于使用。
易于导航

使用分类整齐的文档快速查找和使用资源和端点。
所有浏览器支持

通过适用于所有主要浏览器的 Swagger UI 迎合所有可能的场景。
完全可定制的

样式并通过完整的源代码访问以您想要的方式调整您的 Swagger UI。
完整的 OAS 支持

可视化 Swagger 2.0 或 OAS 3.0 中定义的 API。

二、项目中如何载入Swagger？

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

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

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

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

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

三、如何使用Swagger？

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

1、接口归类

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

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

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

    @Autowired
    BookService bookService;
}

2、接口方法

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

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

@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则会出现以下界面。

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

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

四、配置Swagger

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

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

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

先上代码：

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.baidu.com", "作者Email"))
                .version("1.0")
                .build();
    }

}