【Swagger】2_Swagger 配置

最新推荐文章于 2025-03-04 22:48:54 发布

果将如此

最新推荐文章于 2025-03-04 22:48:54 发布

阅读量663

点赞数 1

分类专栏： # Swagger 文章标签： swagger

By_Code27

本文链接：https://blog.youkuaiyun.com/XJ0927/article/details/109713953

版权

Swagger 专栏收录该内容

3 篇文章

订阅专栏

本文档详细介绍了如何配置Swagger以创建API文档，包括如何通过apiInfo()配置文档信息，选择扫描接口的方式，如basePackage、withMethodAnnotation等，接口扫描过滤，忽略请求参数，启用或禁用Swagger，配置环境依赖的Swagger展示，创建API分组，实体类配置，全局参数设置，以及接口和参数的注解使用。此外，还提到了避免类型转换异常的方法。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

配置 API 文档的信息

通过apiInfo()属性配置文档信息：

/**
 * @Author: xj0927
 * @Description:
 * @Date Created in 2020-11-15 9:49
 */
@Configuration
@EnableSwagger2 //开启swagger
public class SwaggerConfig {

    // 配置docket以配置Swagger具体参数
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
            //通过 apiInfo()属性配置 API 文档信息
            .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("联系人姓名", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");

        return new ApiInfoBuilder()
                .title("Swagger 接口文档") //标题
                .description("文档信息") //描述
                .version("version 1.0") //文档版本
                .contact(contact) //联系人信息
                .build();
    }
}

配置后重启访问可以看到如下：

在这里插入图片描述

配置要扫描的接口

构建 Docket 时通过select()方法配置怎么扫描接口。

@Configuration
@EnableSwagger2 //开启swagger
public class SwaggerConfig {

    // 配置docket以配置Swagger具体参数
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 通过.select()方法，去配置扫描接口
                .select()
                // RequestHandlerSelectors 配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.xj0927.controller"))
                .build()
                ;
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("联系人姓名", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");

        return new ApiInfoBuilder()
                .title("Swagger 接口文档") 
                .description("文档信息") 
                .version("version 1.0") 
                .contact(contact) 
                .build();
    }
}

在这里插入图片描述

除了通过包路径配置扫描接口外，还可以通过配置其他方式扫描接口，这里注释一下所有的配置方式：

any() // 扫描所有，项目中的所有接口都会被扫描到

none() // 不扫描接口

withMethodAnnotation(final Class<? extends Annotation> annotation)// 通过方法上的注解扫描，
如 withMethodAnnotation(GetMapping.class)只扫描get请求

withClassAnnotation(final Class<? extends Annotation> annotation) // 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口

basePackage(final String basePackage) // 根据包路径扫描接口
如basePackage("com.xj0927.controller") 扫描controller 包下的所有controller类

配置接口扫描过滤

上述方式可以通过具体的类、方法等扫描接口，

还可以配置paths()如何通过请求路径配置 [ 筛选显示请求 URL ] ：

// 配置docket以配置Swagger具体参数
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xj0927.controller"))
                // 配置如何通过 path过滤 即这里只扫描 请求以 /user开头的接口
                .paths(PathSelectors.ant("/user/**"))
                .build()
                ;
    }

在这里插入图片描述

这里的可选值还有：

any() // 任何请求都扫描

none() // 任何请求都不扫描

regex(final String pathRegex) // 通过正则表达式控制，返回true扫描，false不扫描

ant(final String antPattern) // 通过ant()表达式控制，返回true扫描，false不扫描

配置要忽略的请求参数

可以通过ignoredParameterTypes()方法去配置要忽略的参数：

/****************** 配置类 ******************/
// 配置docket以配置Swagger具体参数
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
            	// 配置要忽略的参数
                .ignoredParameterTypes(HttpServletRequest.class) 
                .select()
       		    .apis(RequestHandlerSelectors.basePackage("com.example.swaggerexample.controller"))
                .build();
    }


/****************** Controller 类 ******************/
/*这里面的Post请求，由于附带了一个String.class类型的参数*/
@RestController
@RequestMapping(value = "/user")
public class MyController {

    @PostMapping(value = "/test02")
    public String test02(HttpServletRequest，request){
        return "haha";
    }
}

如果 Swagger 没有使用 ignoredParameterTypes 来忽略请求参数，那么请求参数会展示在页面。如果忽略了，就不会进行展示

由于可能会在方法参数会写上 Session 或者 Reques t等敏感信息，所以需要将其忽略

配置是否启动 Swagger

通过enable()方法配置是否启用 swagger，如果是 false，swagger 将不能在浏览器中访问了：

@Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .ignoredParameterTypes(HttpServletRequest.class)
                // 配置是否启用Swagger，如果是false，在浏览器将无法访问
                .enable(false) 
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xj0927.controller"))
                .build();
    }

此时，再访问 swagger

在这里插入图片描述

这样一刀切似乎不太好！！！

由于环境不同，需要设置不同的 Swagger 启动状态。在代码开发环境可以进行访问，但是如果已经上线运行了，还可以通过浏览器访问，就不大合适

通过 Profiles 来设置展示效果

Spring 的测试环境的改变来决定是否启动 Swagger

@Autowired
Environment environment; //注入环境 [ 也可以在 Docker 参数中传入Environment environment ]

@Bean
public Docket docket() {
    // 设置要显示swagger的环境
    Profiles of = Profiles.of("dev", "test");
    // 判断当前是处于该环境，通过 enable() 接收此参数判断是否要显示
    boolean b = environment.acceptsProfiles(of);

    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
        .ignoredParameterTypes(HttpServletRequest.class)
        .enable(b) // 配置是否启用 Swagger，如果是false，在浏览器将无法访问
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.example.swaggerexample.controller")).build();
}

那 swagger 如何知道当前是处于什么环境呢

在这里插入图片描述

你可以在 application-test.yml 中添加 8888 端口，然后访问，看是否可以访问，如果可以访问，那说明确实是指向了 test 配置文件

配置 API 分组

如果没有配置分组，默认是 default。通过groupName()方法即可配置分组：

 @Bean
public Docket docket(Environment environment) {
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
        .groupName("user用户组") // 配置分组
        // 省略配置....
}

在这里插入图片描述

如何配置多个分组？[ 更方便查询 ]

配置多个分组只需要配置多个docket即可：

@Bean
public Docket docket1() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}

如下所示，我们配置了 3 个组：

在这里插入图片描述

配置实体类

（1）通过返回值来进行

这种 Swagger 可以直接扫描到，并且添加到 Models 选项卡里面

比如当前项目中有这么一个实体：

@ApiModel("用户实体") //描述返回的实体信息
public class User {
    
    @ApiModelProperty("用户名")
    private String userName;
    
    @ApiModelProperty("年龄")
    private Integer age;
    
	// 省略getter/setter
}

只要这个实体在 请求接口 的返回值上（即使是泛型），都能映射到实体项中：

在这里插入图片描述

并不是因为 @ApiModel 这个注解让实体显示在这里了，而是只要出现在 [ 接口方法的返回值上的实体 ] 都会显示在这里，

@ApiModel 和 @ApiModelProperty 这两个注解只是为实体添加注释的。

@ApiModel：为类添加注释 
	注解参数的说明：
            value-字段说明 [ 即类说明]
            description-详细描述信息 [ 对类的描述]
    					
@ApiModelProperty：[ 为类属性添加注释 ]
	注解参数的说明：
		   value–字段说明 
            name–重写属性名字 [改变显示的属性名字]
            dataType–重写属性类型 [ 改变属性的类型 ]
            required–是否必填 
            example–举例说明 
            hidden–隐藏

进行了注释之后，展示出来的实体效果为：

在这里插入图片描述

（2）通过入参来进行

这种 Swagger 并不会直接添加，需要一些注解，才能被添加到 Models 选项卡里面

可以通过 @RequestBody 来进行添加

在这里插入图片描述

配置全局参数

什么是全局参数：比如说一个Token 就是一个全局参数

@Bean
public Docket myDocket(){
   Parameter parameter = new ParameterBuilder()
       	    .name("token")  //参数名字
            .description("这是一个令牌")   //参数描述信息
       		.parameterType("header")  //作为一个请求头参数
       		//还有query  表示请求参数
            .modelRef(new ModelRef("String"))  //类型是什么
            .required(true)  //表示这个令牌是必须被填写的
            .build();
    return new Docket(DocumentationType.SWAGGER_2)
           .globalOperationParameters(Arrays.asList(parameter));
}

接口和参数配置

@ApiImplicitParams 注解

value：包含多个 @ApiImplicitParam 注解

@ApiImplicitParams(value = {
        @ApiImplicitParam(name = "username",value = "用户名"),
        @ApiImplicitParam(name = "password",value = "密码")
})
public String test01(String username){
    return "张三"+"  这是Get请求";
}

@ApiImplicitParam 用法说明：

name--参数名 [ 可以写与参数不同的名字，但是最好不要 ]

value–参数说明 

dataType–数据类型

defaultValue--默认参数

paramType–参数类型 

example–举例说明

required--表示是否必须填写

@Api：作用于类

用于表示这个类是 Swagger 的资源

tags--表示说明，如果多个值，就会生成多个list

value--也是说明，可以使用 tags 进行替代

@Api(tags = "处理用户相关的请求",value = "userController")
@RestController
@RequestMapping(value = "/user")
public class UserController {
	....
}

在这里插入图片描述

@ApiOperation：作用于方法

用于描述方法，表示一个 Http 请求的操作

value--用于方法描述 [ 请求的描述信息 ]

notes--用于提示内容

tags--可以重新分组

    @ApiOperation(value = "获取用户信息",notes = "笔记内容",tags = {"分组1","分组2"})
    @PostMapping
    public String add(@RequestHeader("token") String token, String name) {
        return name;
    }

在这里插入图片描述

@ApiParam

对行参进行说明

name--参数名

value--参数说明

required--是否必须填写

    @PutMapping
    public String update(@ApiParam(name = "str",value = "用户名") String str){
        return str;
    }

在这里插入图片描述

@ApiModel：作用与实体类

表示对类进行说明，用于参数，用实体类接收

value–表示对象名 

description–描述

@ApiModelProperty：作用于实体属性

用于方法或者字段，表示对 model 属性说明或者数据操作变更

value--字段说明

name–重写属性名字 
    
dataType–重写属性类型 
    
required–是否必填 
    
example–举例说明 
    
hidden–隐藏

@ApiIgnore：作用于类或者方法上

使得其不在 swagger 的页面上显示出来

NumberFormatException 异常

由于Swagger进行类型转换的时候，会将 example [ 注解的一个参数 ]，进行一个类型转换，它的默认值为 " "，如果你当时的字段类型为 int 等数值类型，那么在进行转换的时候就会出现类型转换的异常

所以，要解决这个问题：

1、要么设置 example 的值

2、换成高版本的 swagger-models 的包 [ 比 1.5.0 高即可 ]