springboot集成swagger 2.X/3.X的方法以及常见报错

最新推荐文章于 2024-09-30 16:50:06 发布

喜欢编程的小王

最新推荐文章于 2024-09-30 16:50:06 发布

阅读量536

点赞数

文章标签：笔记 java spring boot mybatis oneapi

本文链接：https://blog.csdn.net/m0_68118199/article/details/132204773

版权

纯小白一枚，因为前后端分离需要使用到api接口文档，所以才注意到swagger，之前我是完全不是知道这是干什么的。经过信息检索和上手实践后，出现各种问题，下面我将从如何集成到日常使用中容易出现的问题(ps：对于纯小白而言最容易出现的一些问题)

一、集成步骤及问题

集成步骤可以看这篇文章，写的真的很详细，不管swagger2.x还是3.x都有详细介绍：https://blog.csdn.net/lsqingfeng/article/details/123678701

总的来讲就是：

1.引入依赖(这里有一个注意的问题：如果你跟我一样配置完成之后一开始访问api文档控制台就报异常：

Illegal DefaultValue null for parameter type integer
NumberFormatException: For input string: ""

这是因为swagger自带的annotations和models依赖为1.5.20版本的，实体类使用@ApiModelProperty时，example属性没有赋值导致的，在AbstractSerializableParameter的getExample方法中会将数值属性的example的转换数值类返回，example的默认值是""，因此当example没有赋值时，会出现上面的异常。其源码路径为io.swagger.models.parameters.AbstractSerializableParameter.getExample()

（ps：可参考：https://blog.csdn.net/weixin_44299027/article/details/105810872）

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
        <!--解决 Illegal DefaultValue null for parameter type integer 异常-->
        <!--1.排除swagger2的annotations和models依赖-->
        <exclusions>
            <exclusion>
                <groupId>io.swagger</groupId>
                <artifactId>swagger-annotations</artifactId>
            </exclusion>
            <exclusion>
                <groupId>io.swagger</groupId>
                <artifactId>swagger-models</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    <!--2.引入1.5.21以上版本的annotations和models依赖-->
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-annotations</artifactId>
        <version>1.5.21</version>
    </dependency>
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-models</artifactId>
        <version>1.5.21</version>
    </dependency>
    <!--  swagger-ui增强(一般都会使用ui增强工具，swagger自带的ui贼丑而且不直观便捷)  -->
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>swagger-bootstrap-ui</artifactId>
        <version>1.9.6</version>
    </dependency>

2.进行配置
首先需要添加一个注解： @EnableSwagger2。这个注解可以直接添加到SpringBoot的启动类上，也可以自定义一个配置类，放到上面。添加这个注解代表在项目中开启Swagger的功能。

一般都是自己定义一个配置类，正好还可以添加一个Docket配置。可以自定义Docket配置，就是一组(一个项目或一个版本)接口文档的配置，比如设置名称，联系人等等。

在config文件夹下，添加一个SwaggerConfig类

package com.wc.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.spring.web.plugins.Docket;
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.swagger2.annotations.EnableSwagger2;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;

import java.util.ArrayList;

/**
 * @author WangChen 2064318526@qq.com
 * @date 2023/8/10 16:09
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createDocket(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2)
            // 设置是否启动Swagger，默认为true（不写即可），关闭后Swagger就不生效了
            .enable(true)
            // 分组名称
            .groupName("Demo")
            // 文档信息配置
            .apiInfo(apiInfo())
            // 配置扫描的接口
            .select()
            // 配置扫描哪里的接口
            .apis(RequestHandlerSelectors.basePackage("com.wc.demo.controller"))
            // 过滤请求
            .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
            .title("WangChen接口文档")//文档标题
            .description("记录项目接口")//文档基本描述
            .contact(new Contact("wangchen", "https://blog.csdn.net/m0_68118199", "2064318526@qq.com"))//这里可以添加联系人信息
            .termsOfServiceUrl("http://terms.service.url/WangChen") // 组织链接
            .version("v1.0")//版本
            .license("Apache 2.0 许可") // 许可
            .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0") // 许可链接
            .extensions(new ArrayList<>()) // 拓展
            .build();
    }
}

3.yml文件添加以下内容：

spring:
  mvc:
    pathmatch:
      matching-strategy: ANT_PATH_MATCHER

4.之后就可以开始使用了，在控制层和类对象中使用注解进行说明就行。如果想仅在测试环境test，开发环境dev中使用api文档；yml中加入：

spring:
  mvc:
    pathmatch:
      matching-strategy: ANT_PATH_MATCHER
  profiles:
    active: dev # 可换

配置类中的docket中改为这样：

@Bean
    public Docket docket1(Environment environment){
        Profiles profiles = Profiles.of("dev", "test"); // 设置要显示swagger的环境
        boolean isOpen = environment.acceptsProfiles(profiles); // 判断当前是否处于该环境
        return new Docket(DocumentationType.SWAGGER_2)
            // 设置是否启动Swagger，默认为true（不写即可），关闭后Swagger就不生效了
            .enable(isOpen)
            // 分组名称
            .groupName("Demo")
            // 文档信息配置
            .apiInfo(apiInfo())
            // 配置扫描的接口
            .select()
            // 配置扫描哪里的接口
            .apis(RequestHandlerSelectors.basePackage("com.wc.demo.controller"))
            // 过滤请求
            .paths(PathSelectors.any())
            .build();
    }

这样就只能在dev环境中显示接口文档了

二、使用中的一些问题

1.接口文档不显示请求参数，不显示响应参数----注解描述

2.显示请求参数和响应参数，但是参数说明不显示

3.仅显示部分参数

解决思路：检查描述性注解是否使用得当，检查字段命名是否符合驼峰命名。

一般控制层使用@Api()描述类，@ApiOperation()描述接口，参数校验实体类中使用ApiModel()描述实体类@ApiModelProperty()描述属性@ApiParam()描述参数，且可对属性进行是否必传的描述注解@NotBlank()（一般用于String类型）@NotNull()等。