【SpringBoot项目集成Swagger框架】

---

---

提示：以下是本篇文章正文内容，下面案例可供参考

一、Swagger是什么？

• RestFul Api 文档在线自动生成工具==>主要用来Api文档和API定义代码自动同步更新
• 可以直接运行，在线测试API接口
• 支持多种语言 （JAVA，PHP…）

官方网站
https://swagger.io/

二、集成Swagger步骤

1.创建Spring boot - Web 项目

2.创建一个hello工程

• 在swagger下面创建controller文件，里面创建 HelloController 类
  
• 然后运行启动类，从浏览器进入localhost：8080/hello 界面，这样我们一个简单的项目就搭建成功了
  

3.导入相关依赖

在项目中使用Swagger需要导入 springbox；

• swagger2
• ui

<!-- https://search.maven.org/artifact/io.springfox/springfox-swagger2/2.9.2/jar -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

        <!-- https://search.maven.org/artifact/io.springfox/springfox-swagger-ui/2.9.2/jar -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

• 导入依赖后，等待下载完成
  

4.配置 Swagger --> Config

@Configuration  //注解添加Config到SpringBoot中
@EnableSwagger2  //开启Swagger2
public class SwaggerConfig {
    
}

5.测试运行

访问http://localhost:8080/swagger-ui.html页面

6.配置Swagger

Swagger的bean实例 Docket；

//配置Swagger的Docket的Bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    //配置Swagger 信息 --》 apiInfo
    private ApiInfo apiInfo(){

        //作者信息
        Contact contact = new Contact("hwh", "https://blog.csdn.net/kelekele111?type=blog", "123");

        return new ApiInfo(
                "哈哈哈哈",
                "Api----Swagger----Demo",
                "1.0",
                "https://blog.csdn.net/kelekele111?type=blog",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

配置完成后运行的界面：

7.Swagger配置扫描接口

//配置Swagger的Docket的Bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //RequestHandlerSelectors,配置要扫描接口的方式，basePackage说明扫描包
                .apis(RequestHandlerSelectors.basePackage("com.hwh.swagger.controller"))
                .build();
    }

代表只扫描controller下的接口

运行界面如下：

Docket.select()

//配置Swagger的Docket的Bean实例
    //Docket.select()
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //RequestHandlerSelectors,配置要扫描接口的方式，.basePackage说明指点要扫描的包
                //.apis(RequestHandlerSelectors.basePackage("com.hwh.swagger.controller"))
                //
                //.any():扫描全部
                //.apis(RequestHandlerSelectors.any())
                //none():不扫描
                //withClassAnnotation():扫描类上的注解，需要的参数是一个注解的反射对象
                //withMethodAnnotation():扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.hwh.swagger.controller"))
                //paths():过滤什么路径
                .paths(PathSelectors.ant("/hwh/**"))
                .build();
    }

8.配置是否启动swagger

//配置Swagger的Docket的Bean实例
    //Docket.select()
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //enable():ture为启用swagger，false为不启用
                .enable(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.hwh.swagger.controller"))
                .build();
    }

9.解决在不同环境下运行swagger

1.先在数据源下创建两个测试和生产的

2.分别写端口为8081和8082

3.在application.properties文件中配置为测试环境，这样就不用动代码，只需要改写配置文件就行

//配置Swagger的Docket的Bean实例
    //Docket.select()
    @Bean
    public Docket docket(){
    	//设置要显示的swagger环境
        Profiles profiles = Profiles.of("dev","test");

        //通过environment.acceptsProfiles 判断是否处在自己设置的环境中
        boolean flag = environment.acceptsProfiles(profiles);
        
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //enable():ture为启用swagger，false为不启用
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.hwh.swagger.controller"))
                .build();
    }

dev环境运行界面，端口为8081

10.配置API文档的分组

.groupName(“Hello1”)

如何多个下拉列表，只需要多建几个Docket实例就行


实体类配置

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用户实体类")  //注解类名字
public class User {

    @ApiModelProperty("密码")  //注解类属性名字
    public String password;
    @ApiModelProperty("用户名")
    public String username;

}

我们也可以在swagger里面测试接口

---

报错&总结

java.lang.NoSuchMethodError: java.util.Set.of(Ljava/lang/Object;)Ljava/util/Set;

说明版本过高导致冲突，需要更换Spring boot版本为2.5.7

---

总结：
1.我们可以通过Swagger给一些比较难理解的接口或者属性写注释信息，分别理解
2.接口文档实时更新
3.可以在线测试
【注意点】如果为生产的项目，应该在正式发布的时候关闭swagger，能节省运行空间和安全保障接口的调用