当前位置 博文首页 > 文章内容

    码上言:从零学习Swagger3.0(最全讲解)

    作者:21344 栏目:未分类 时间:2021-11-25 22:15:30

    一、什么是Swagger?

    1、前言

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

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

    配置完,重启项目,效果如下:

    image-20210910222230356

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

    image-20210910222509700

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

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

    微信公众号:码上言

    cs