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

相关推荐
公贵买其鹿14 分钟前
List深拷贝后,数据还是被串改
java
向前看-3 小时前
验证码机制
前端·后端
xlsw_3 小时前
java全栈day20--Web后端实战(Mybatis基础2)
java·开发语言·mybatis
神仙别闹4 小时前
基于java的改良版超级玛丽小游戏
java
黄油饼卷咖喱鸡就味增汤拌孜然羊肉炒饭5 小时前
SpringBoot如何实现缓存预热?
java·spring boot·spring·缓存·程序员
暮湫5 小时前
泛型(2)
java
超爱吃士力架5 小时前
邀请逻辑
java·linux·后端
南宫生5 小时前
力扣-图论-17【算法学习day.67】
java·学习·算法·leetcode·图论
转码的小石5 小时前
12/21java基础
java
李小白665 小时前
Spring MVC(上)
java·spring·mvc