行业资讯 2025年08月6日
0 收藏 0 点赞 221 浏览 5392 个字
摘要 :

文章目录 一、传统维护API文档缺点 二、Swagger2介绍 三、IDEA+SpringBoot整合Swagger2 第一步:导入依赖 第二步:创建Swagger配置类 第三步:API 接口编写 第四步:启……




  • 一、传统维护API文档缺点
  • 二、Swagger2介绍
  • 三、IDEA+SpringBoot整合Swagger2
    • 第一步:导入依赖
    • 第二步:创建Swagger配置类
    • 第三步:API 接口编写
    • 第四步:启动项目访问测试
    • 补充:在 Security 中的配置

    一、传统维护API文档缺点

    当下很多公司都采取前后端分离的开发模式,前端和后端的工作由不同的开发人员完成。在这种开发模式下,维护一份及时更新且完整的REST API文档将会极大的提高我们的工作效率。传统意义上的文档都是后端开发人员手动编写的,相信大家也都知道这种方式很难保证文档的及时性,长期以往这种文档也就会失去其参考意义,反而还会加大前后端之间的沟通成本,严重影响开发效率,更有甚者,由于沟通不畅导致业务上的漏洞,其危害与严重性可想而知。

    二、Swagger2介绍

    wagger2 的出现就是为了从根本上解决传统人工维护API文档的缺点。它作为一个规范和完整的框架,可以用于生成、描述、调用和可视化 RESTful 风格的 Web 服务:

    • 接口文档在线自动生成,文档随接口变动实时更新,节省维护成本
    • 支持在线接口测试,不依赖第三方工具

    访问Swagger官网

    三、IDEA+SpringBoot整合Swagger2

    第一步:导入依赖

    首先在SpringBoot项目的pom.xml中导入如下依赖:

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
    

    第二步:创建Swagger配置类

    我们可以在config目录下新建Swagger的配置类Swagger2Configuration.java,具体代码如下:

    package com.panziye.demo.config;
    
    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.service.ApiInfo;
    import springfox.documentation.service.Contact;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    /**
     * @author panziye
     * @version 1.0
     * @date 2021-08-02 13:53
     * @description <p></p>
     **/
    @Configuration
    @EnableSwagger2
    public class Swagger2Configuration {
    
        /**
         * api接口包扫描路径
         */
        public static final String SWAGGER_SCAN_BASE_PACKAGE = "com.panziye.demo.controller";
    
        public static final String VERSION = "1.0.0";
    
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                // 随便起
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                // 可以根据url路径设置哪些请求加入文档,忽略哪些请求
                .paths(PathSelectors.any())
                .build();
        }
    
        private ApiInfo webApiInfo() {
            return new ApiInfoBuilder()
                //设置文档的标题
                .title("Swagger2测试案例")
                // 设置文档的描述
                .description("Swagger2测试案例 API 接口文档")
                // 设置文档的版本信息-> 1.0.0 Version information
                .version(VERSION)
                // 联系人和联系方式
                .contact(new Contact("panziye", "https://www.panziye.com", "1562691348@qq.com"))
                // 设置文档的License信息->1.3 License information
                .license("The Apache License")
                .licenseUrl("https://www.panziye.com")
                .build();
        }
    }
    

    Swagger2Configuration.java 配置类的内容不多,配置完成后也很少变化,简单了解即可。

    如上代码所示,通过 @Configuration 注解,让 Spring 加载该配置类。再通过 @EnableSwagger2 注解来启用Swagger2。成员方法 createRestApi 函数创建 Docket 的Bean之后,webApiInfo() 用来创建该 Api 的基本信息(这些基本信息会展现在文档页面中)。select() 函数返回一个 ApiSelectorBuilder实例用来控制哪些接口暴露给 Swagger 来展现,本例采用指定扫描的包路径来定义,Swagger 会扫描该包下所有 Controller 定义的 API,并产生文档内容(除了被 @ApiIgnore 指定的请求)。

    第三步:API 接口编写

    在完成了上述配置后,其实已经可以产生文档内容,但是这样的文档主要针对请求本身,而描述主要来源于函数等命名产生,对用户并不友好,我们通常需要自己增加一些说明来丰富文档内容。
    潘老师在com.panziye.demo.controller包下新建了UserController用来测试,具体代码如下:

    package com.panziye.demo.controller;
    
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiImplicitParam;
    import io.swagger.annotations.ApiImplicitParams;
    import io.swagger.annotations.ApiOperation;
    import io.swagger.annotations.ApiResponse;
    import io.swagger.annotations.ApiResponses;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.PathVariable;
    import org.springframework.web.bind.annotation.PostMapping;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RequestParam;
    import org.springframework.web.bind.annotation.RestController;
    
    /**
     * @author panziye
     * @version 1.0
     * @date 2021-08-02 14:05
     * @description <p></p>
     **/
    
    @RestController
    @RequestMapping("/user")
    @Api(tags = {"用户控制类"})
    public class UserController {
    
        @PostMapping("/login")
        @ApiOperation(value = "登录接口")
        @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", required = true, paramType = "query"),
            @ApiImplicitParam(name = "password", value = "密码", required = false, paramType = "query"),
        })
        @ApiResponses({
            @ApiResponse(code = 400, message = "请求参数没填好"),
            @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
        })
        public String login(@RequestParam("username") String username, @RequestParam("password") String password) {
            return "success";
        }
    
        @PostMapping("/register")
        @ApiOperation(value = "注册接口")
        public String register(@RequestParam("username") String username,@RequestParam("password") String password) {
            return "success";
        }
    
        @GetMapping("/get/{id}")
        @ApiOperation(value = "根据id获取用户信息")
        public String getUser(@PathVariable("id")int id){
            return "success";
        }
    
    }
    

    本接口示例了 @ApiOperation 和 @ApiImplicitParam 两个注解的使用。Swagger 通过注解定制接口对外展示的信息,这些信息包括接口名、请求方法、参数、返回信息等。更多注解类型:

    • @Api:修饰整个类,描述Controller的作用
    • @ApiOperation:描述一个类的一个方法,或者说一个接口
    • @ApiParam:单个参数描述
    • @ApiModel:用对象来接收参数
    • @ApiProperty:用对象接收参数时,描述对象的一个字段
    • @ApiResponse:HTTP响应其中1个描述
    • @ApiResponses:HTTP响应整体描述
    • @ApiIgnore:使用该注解忽略这个API
    • @ApiError :发生错误返回的信息
    • @ApiImplicitParam:描述一个请求参数,可以配置参数的中文含义,还可以给参数设置默认值
    • @ApiImplicitParams:描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表

    第四步:启动项目访问测试

    我们期待SpringBoot项目,在浏览器访问http://localhost:8080/swagger-ui.html地址,发现如下:
    IDEA+SpringBoot整合Swagger2实现自动创建API接口文档详解

    IDEA+SpringBoot整合Swagger2实现自动创建API接口文档详解
    注意:如果出现如下错误,请访问如下文章解决:
    IDEA+SpringBoot整合Swagger2实现自动创建API接口文档详解

    SpringBoot集成Swagger2报错Unable to infer base url. This is common…API Gateway

    在使用IDEA+SpringBoot集成Swagger2时发现SpringBoot启动正常,没有报错,但当使用 […]

    补充:在 Security 中的配置

    如果你的Spring Boot 项目中如果集成了 Spring Security,在不做额外配置的情况下,Swagger2 文档会被拦截。解决方法是在 Security 的配置类中重写 configure 方法添加白名单即可:

    @Override
    public void configure ( WebSecurity web) throws Exception {
        web.ignoring()
          .antMatchers("/swagger-ui.html")
          .antMatchers("/v2/**")
          .antMatchers("/swagger-resources/**");
    } 
    

    OK,以上就是IDEA+SpringBoot整合Swagger2实现自动创建API接口文档详解内容。

微信扫一扫

支付宝扫一扫

版权: 转载请注明出处:https://www.zuozi.net/8048.html

管理员

相关推荐
2025-08-06

文章目录 一、Reader 接口概述 1.1 什么是 Reader 接口? 1.2 Reader 与 InputStream 的区别 1.3 …

988
2025-08-06

文章目录 一、事件溯源 (一)核心概念 (二)Kafka与Golang的优势 (三)完整代码实现 二、命令…

465
2025-08-06

文章目录 一、证明GC期间执行native函数的线程仍在运行 二、native线程操作Java对象的影响及处理方…

348
2025-08-06

文章目录 一、事务基础概念 二、MyBatis事务管理机制 (一)JDBC原生事务管理(JdbcTransaction)…

456
2025-08-06

文章目录 一、SnowFlake算法核心原理 二、SnowFlake算法工作流程详解 三、SnowFlake算法的Java代码…

517
2025-08-06

文章目录 一、本地Jar包的加载操作 二、本地Class的加载方法 三、远程Jar包的加载方式 你知道Groo…

832
发表评论
暂无评论

还没有评论呢,快来抢沙发~

助力内容变现

将您的收入提升到一个新的水平

点击联系客服

在线时间:08:00-23:00

客服QQ

122325244

客服电话

400-888-8888

客服邮箱

122325244@qq.com

扫描二维码

关注微信客服号