IDEA中SpringBoot配置Swagger详细(问题)

混蛋姗姗

已于 2022-07-08 09:26:15 修改

阅读量4.7k

点赞数

文章标签：测试工具 fiddler spring boot

于 2022-07-08 09:17:07 首次发布

本文链接：https://blog.csdn.net/hundanshanshan/article/details/125671057

版权

Swagger是什么？
现在比较流行的是前后端分离的开发方式，后端写好接口后撰写接口文档，前端根据接口文档调用接口进行开发。

Swagger主要是自动生成接口文档的一个工具，并且附带测试接口（类似Postman）功能。

为什么要用Swagger？
接口文档谁写谁知道，繁琐，容易出错，且每个人的写法，风格等不好去规范。

用起Swagger解放双手，减少错误，规范文档，实时方便可调试，对于前端后端都是一件好事。

配置步骤：

1.导入依赖，Swagger2.X.X版本和Swagger3.0.0有较大改动，此处以2.9.2作为示例。关于Swagger3.0.0文章最后有涉及和表述。

在SpringBoot项目的pom.xml文件中添加依赖，<dependencies>标签下，添加后IDEA底部依赖项中可查看到。

        <!--Swagger2依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

PS：如你在使用2.9.2或以上版本出现兼容问题，请移步此博客。

2.编写Swagger配置类

项目中构建controller同级文件包config，新建SwaggerConfig类

@Configuration 声明为配置类

@EnableSwagger2 启用Swagger注解

特别注意方法中扫描API的路径换成自己的项目包路径，否则运行起来后无法找到接口。

/**
 * Swagger的配置类
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    //测试API
    @Bean
    public Docket myDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("测试")
                .apiInfo(myApiInfo())//调用的api描述方法
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.newdemoswagger"))//扫描的API包路径
                .build();
    }

    public ApiInfo myApiInfo() {
        return new ApiInfoBuilder()
                .title("测试API文档")
                .version("1.0")
                .build();
    }

}

PS：groupName表示分组，如果要建立多个组别，写多组docket和apiInfo方法就好了。

3.编写实体类

这一步是在bean层，或者说DAO、Domain，Entity，叫法不同，实际指的就是实体类。

@ApiModel用于实体类上，value表示对象名，description表示对象描述。

4、编写Controller类

@Api 表示这个类是swagger的资源，value和tags都是接口说明

@ApiOperation 用于方法上，value表示接口描述，notes表示提示内容

@ApiParam用于参数上，name表示参数名，notes表示参数说明，required表示表示是否必填，值为true或false

5、访问测试

项目启动后，访问地址：http://IP:端口号/swagger-ui.html

PS：这个是默认地址，ip和端口号根据情况自行修改。

问题：启动网址后如显示Whitelabel Error Page，则只需在config文件中添加一段代码。

由于项目中有配置注解类（@Configuration）继承了WebMvcConfigurationSupport，导致默认的Swagger静态资源被覆盖，而缺失了配置。

可在该继承配置类中，显式添加如下swagger静态资源：

protected void addResourceHandlers(ResourceHandlerRegistry registry){
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

打包部署重启，可以了，来看效果吧！

Swagger3.0

区别主要在于pom.ml和SwaggerConfig配置类中,访问地址也有所变化。

pom.xml

        <!-- 需要注意springboot版本2.5.7 与swagger3.0.0 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

SwaggerConfig

/**
 * Swagger配置类，该类里面的应该是固定的，主要用来设置文档的主题信息，比如文档的大标题，副标题，公司名
 */
@Configuration//托管spring
public class SwaggerConfig {
 
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30) // v2 不同
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.springbootmybatisplus"))//扫描该包下面的API注解
                .build();
    }
 
 
}

访问地址：http://地址:端口/swagger-ui/index.html