SpringBoot 集成 Swagger

1. 2.9 版本 Swagger 安装使用

1.1 加依赖

            <!--swagger接口管理-->
            <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>

1.2 新建配置类

import com.janet.common.constant.RespCodeEnum;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RequestMethod;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.ResponseMessage;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

/**
 * @Description swagger配置文件
 * 使用方法：添加依赖，添加配置类，在实体类、controller类以及方法上添加相应注解
 * 访问地址：http://localhost:8003/swagger-ui.html
 */
//@Profile({"SIT","UAT"})
@Configuration
@EnableSwagger2//加载swagger
public class SwaggerConfig {

    @Bean
    public Docket api(){
        //添加全局响应状态码
        List<ResponseMessage> responseMessageList = new ArrayList<>();
        Arrays.stream(RespCodeEnum.values()).forEach(errorEnums -> {
            responseMessageList.add(
                    new ResponseMessageBuilder().code(errorEnums.getStatusCode()).message(errorEnums.getMsg()).responseModel(
                            new ModelRef(errorEnums.getMsg())).build()
            );
        });
        return new Docket(DocumentationType.SWAGGER_2)
                // 添加全局响应状态码
                .globalResponseMessage(RequestMethod.GET, responseMessageList)
                .globalResponseMessage(RequestMethod.POST, responseMessageList)
                .globalResponseMessage(RequestMethod.PUT, responseMessageList)
                .globalResponseMessage(RequestMethod.DELETE, responseMessageList)
                .apiInfo(apiInfo())
                .pathMapping("/")//配置访问路径
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.janet.controller")) // 配置swagger显示的controller，如果不配置则默认扫描所有后端接口
                .paths(PathSelectors.regex("/.*"))//匹配路径下的方法
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Janet练习项目相关接口集")
                .description("Janet练习项目相关接口集")
                .version("1.0.0")
                .contact(new Contact("JanetTestDemo-lottery", "https://gitee.com/liyingdan/cloud2020", "7161@outlook.com"))
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .build();
    }

}

 添加全局响应状态码大概就是这种效果：

其中，ErrorEnums 是我自己写的一个枚举类。

public enum ErrorEnums {
    SUCCESS_STATUS(200,"操作成功"),
    FAILED_STATUS(201,"操作失败"),
    USER_TOKEN_EXPIRED(202,"登录超时");

    //错误码
    public int code;
    //提示信息
    public String message;

    ErrorEnums(int code, String message){
        this.code = code;
        this.message = message;
    }

    //获取状态码
    public int getCode(){
        return code;
    }

    //获取提示信息
    public String getMessage(){
        return message;
    }

    public Integer toInt() {
        return this.code;
    }
}

1.3 对象类和Controller类添加注解接口

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value="活动对象",description="****活动表")
public class SmActivity {
    @ApiModelProperty(value = "活动ID")
    private Long activityId;

    @ApiModelProperty(value = "活动名称")
    private String activityName;
}

@RestController
@RequestMapping
@Api(value = "ActivityController",tags = "活动获取接口") //@Api注解可以用来标记当前Controller的功能。
public class ActivityController {


	@Autowired
	private ActivityService activityService;

	@RequestMapping("/{userId}/{token}/getUserList")
	@ApiOperation(value = "获取名单列表",httpMethod = "POST") //@ApiOperation注解用来标记一个方法的作用。
	public String getUserList(@ApiParam(name = "userId",value = "用户Id",required = true) @PathVariable("userId")Integer userId){
        ..........
        ..........
        ..........
	}

	
    @ApiOperation(value = "方法注释",httpMethod = "GET")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "startTime",value = "开始时间",required = true,type = "String"),
            @ApiImplicitParam(name = "endTime",value = "结束时间",required = true,type = "String")
    }) //ApiImplicitParams 用来标注这个方法所用到的参数，效果如下图
    @ApiResponses({
            @ApiResponse(code = 200, message = "提示", response = LogisticsInfoVo.class, responseContainer = "List")})
    @GetMapping(value = "/getDetail")
    public void getDetail(String startTime, String endTime)  {
        .............
        ...........

    }

}

访问接口：

[项目访问地址]/swagger-ui.html

常用注解：

• @Api() 用于 controller 类：表示标识这个类是 swagger 的资源
• @ApiOperation() 用于方法：表示一个 http 请求的操作
• @ApiParam() 用在 @ApiImplicitParams 的方法里边，定义接收的参数形式：表示对参数的添加元数据（说明或是否必填等）
• @ApiModel() 用于类：表示对类进行说明，用于参数用实体类接收
• @ApiModelProperty() 用于方法，字段：表示对 model 属性的说明或者数据操作更改
• @ApiIgnore() 用于类，方法，方法参数：表示这个方法或者类被忽略
• @ApiImplicitParams() 用于 controller 方法，包含多个 @ApiImplicitParam
• @ApiImplicitParam() 用 在@ApiImplicitParams 的方法里边：表示单独的请求参数

2. 3.0.0 版本 Swagger 使用

步骤其实和上面一样，只是3.0.0整合了依赖，只用导入下面一个依赖就好了。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

配置类也和上面一样，如果不想添加自定义状态码也是可以的。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @Description swagger配置文件
 * 使用方法：添加依赖，添加配置类，在实体类、controller类以及方法上添加相应注解
 * 访问地址：http://localhost:8004/swagger-ui/index.html
 */
@Configuration
@EnableSwagger2//加载swagger
public class SwaggerConfig {

    @Bean
    public Docket docket() {
        ApiInfo apiInfo =
                new ApiInfoBuilder()
                        .title("JanetTestDemo-consumer接口文档")
                        .description("Janet练习项目相关接口集 customer module，API文档集成Swagger")
                        .version("1.0")
                        .build();

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                // 配置swagger显示的controller，如果不配置则默认扫描所有后端接口
                .apis(RequestHandlerSelectors.basePackage("com.janet.customer.controller"))
                .paths(PathSelectors.any())
                .build();
    }

}

接口访问地址也变了，我的是：http://localhost:8004/swagger-ui/index.html

其中8004是我的应用端口。

3. 访问index.html会报错？

我在访问 swagger-ui/index.html 页面时，页面没有异常，但是控制台报错了：

2023-07-06 11:30:08.432 WARN  - [0 1443] - Illegal DefaultValue null for parameter type integer
java.lang.NumberFormatException: For input string: ""
	at java.lang.NumberFormatException.forInputString(NumberFormatException.java:65)
	at java.lang.Long.parseLong(Long.java:601)
	at java.lang.Long.valueOf(Long.java:803)
	at io.swagger.models.parameters.AbstractSerializableParameter.getExample(AbstractSerializableParameter.java:412)
	at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
	at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
	at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
	at java.lang.reflect.Method.invoke(Method.java:483)
	at com.fasterxml.jackson.databind.ser.BeanPropertyWriter.serializeAsField(BeanPropertyWriter.java:689)
	at com.fasterxml.jackson.databind.ser.std.BeanSerializerBase.serializeFields(BeanSerializerBase.java:723)
	at com.fasterxml.jackson.databind.ser.BeanSerializer.serialize(BeanSerializer.java:166)

报错原因，这边文章写的很详细了：【异常处理】关于访问swagger-ui报错java.lang.NumberFormatException: For input string: ““的解决方案总结_No8g攻城狮的博客-CSDN博客

我这里的处理方式：排查原依赖中的swagger-models，另外引入

        <!--swagger接口管理-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <!--在springfox-boot-starter 3.0.0版本依赖中的springfox-swagger2中依赖的swagger-models是1.5.20版本，
            该版本会导致For input string: ""错误，所以排除这个版本。另外添加swagger-models依赖-->
            <exclusions>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.21</version>
        </dependency>

然后重启之后就不会报错啦~

---

swagger注释API详细说明

Swagger2.X注解