Spring Boot整合swagger

你可能尝试过写完一个接口后,自己去创建接口文档,或者修改接口后修改接口文档。多了之后,你肯定会发生一个操作,那就是忘记了修改文档或者创建文档(除非你们公司把接口文档和写接口要求得很紧密😓忘记写文档就扣工资?,否则两个分离的工作总是有可能遗漏的)。而swagger就是一个在你写接口的时候自动帮你生成接口文档的东西,只要你遵循它的规范并写一些接口的说明注解即可。

  • 自动生成文档,只需要在接口中使用注解进行标注,就能生成对应的接口文档。
  • 自动更新文档,由于是动态生成的,所以如果你修改了接口,文档也会自动对应修改(如果你也更新了注解的话)。这样就不会发送我修改了接口,却忘记更新接口文档的情况。
  • 支持在线调试,swagger提供了在线调用接口的功能。

前端要接口,写文档

在springBoot项目中使用

1、导入依赖

springboot 版本有时候版本和swagger版本不兼容,但是我测试了一下,我们使用的springboot版本和2.9.12这个是兼容的

复制代码
<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配置类,也可以在springboot配置文件中配置,但是我定义了多个测试环境,就直接定义了自定义配置类

复制代码
package com.yy.config;


import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
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;

import java.util.ArrayList;

@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI  // 开启SwaggerBootstrapUI
//@Profile({"dev", "test"}) // 设置swagger的使用环境(防止prod环境api泄露)
public class SwaggerConfig {
    @Bean
    public Docket docket(Environment environment){
        //指定在dev/test环境下使用swagger
        Profiles profiles = Profiles.of("dev","test");
        System.out.println(profiles);
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("第一个docker")// 如果配置多个文档的时候,那么需要配置groupName来分组标识
                .apiInfo(apiInfo()) // 用于生成API信息
                .enable(flag)//关闭swagger,默认是true
                .select() //select()函数返回一个ApiSelectorBuilder实例,用来控制接口被swagger做成文档
                //RequestHandlerSelectors:配置要扫描的方式,有basePackage("路径")、any():扫描全部,none():全部不扫描
                //RequestHandlerSelectors.withMethodAnnotation():扫描方法上的注解
                //.withClassAnnotation():扫描类上的注解
                .apis(RequestHandlerSelectors.basePackage("com.yy.controller"))//指定扫描的包
               //.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
               //.withMethodAnnotation(PostMapping.class) // 扫描带有指定注解的方法接口
                //.apis(RequestHandlerSelectors.any()) // 扫描所有
                .paths(PathSelectors.any()
                           //.any() // 满足条件的路径,该断言总为true
                         //.none() // 不满足条件的路径,该断言总为false(可用于生成环境屏蔽 swagger)
                         //.ant("/user/**") // 满足字符串表达式路径
                        // .regex("") // 符合正则的路径
                )//设置请求路径,这里是带有hello的请求路径
                .build();
    }

    private ApiInfo apiInfo(){
        //定义作者的姓名,网址,邮箱
        Contact contact = new Contact("大米饭", "http://t.csdnimg.cn/zEtOU", "224578908@qq.com");

      return new ApiInfoBuilder()
                .title("大米的项目API") //  可以用来自定义API的主标题
                .description("XX项目SwaggerAPI管理") // 可以用来描述整体的API
                .termsOfServiceUrl("https://www.baidu.com") // 用于定义服务的域名(跳转链接)
                .version("1.0") // 可以用来定义版本
                .license("Swagger-的使用教程")
                .licenseUrl("https://blog.csdn.net")
                .contact(contact)
                .build(); //
    }
}

那既然是记录了接口文档,肯定不能在生产环境中使用 在swagger配置类中配置了在什么环境下可以查看接口及记录的接口文档

定义了3个环境的配置类,定义使用那个环境的配置类,模拟了一下只配置了端口,生产环境用的8081,在配置类中拿现在环境,进行判断,如果是生产环境关闭swagger

定义了两个controller类,用来测试接口

复制代码
@ApiOperation(value = "测试方法",notes = "用户测试notes")相当于是一个分组,就像我们用rustful 工具时,先是一个controller类目录,然后,下面有post,get,put方法

启动启动类

在浏览器中输入:

查看没有使用uI的接口文档:http://localhost:8081/swagger-ui.html

@ApiOperation(value = "用户测试",notes = "用户测试notes")

使用ui界面需要添加依赖

在配置文件上开启ui

启动启动类

使用了uI的接口文档:http://localhost:8081/doc.html,即可预览到基于bootstarp的Swagger UI界面

他只能提供一个简单的在线调试,如果你想存储你的测试用例,不能像Postman或者YAPI这样保存了你的测试记录

没有接口文档更新管理,在文档有大的更新的时候可以提前导出一下文档

参考链接:http://t.csdnimg.cn/KnIVB

相关推荐
nice_lcj5204 分钟前
【从零理解计算机网络 · 05】TCP 四次挥手:为什么挥手要四次、TIME_WAIT 在等什么
后端·tcp/ip·计算机网络·面试·tcp·四次挥手·time_wait
Moment11 分钟前
RSI 是怎样让 AI 改进自己的 ❓❓❓
前端·后端·面试
Cosolar22 分钟前
从 50ms 到 3 分钟:淘特动线 Agent 如何把 LLM 塞进一个有预算约束的实时系统
人工智能·后端·agent
Cosolar30 分钟前
拆开「研发数字人」:一个 Agent 系统真正的护城河,是被结构化的判断力
人工智能·后端·架构
Rain的Java大神之路39 分钟前
LeetCode 40 组合总和 II:面试官想听的不是回溯,而是那行去重代码
java·leetcode·面试
cong_1 小时前
🐟 我把摸鱼岛重写了!现在群聊还能装进一张表格
前端·后端·github
wno7041 小时前
Centos下PostgreSQL安装部署详细步骤
java·数据库·spring boot
nice_lcj5202 小时前
【从零理解计算机网络 · 04】TCP 三次握手:为什么恰好是三次
java·后端·tcp/ip·计算机网络·面试·tcp·三次握手
JaguarJack2 小时前
NGINX 两处漏洞可导致未经身份验证的远程代码执行(CVE-2026-123633 和 CVE-2026-123007)
后端·nginx·nginx2root
BingoGo2 小时前
NGINX 两处漏洞可导致未经身份验证的远程代码执行(CVE-2026-123633 和 CVE-2026-123007)
后端·nginx