SpringBoot项目中使用Swagger2及注解解释（详细）

Posted 2023-04-09 nianyuw

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了SpringBoot项目中使用Swagger2及注解解释（详细）相关的知识，希望对你有一定的参考价值。

SpringBoot项目中使用Swagger2及注解解释

这里写目录标题

- - SpringBoot项目中使用Swagger2及注解解释

一、导入Swagger坐标依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>$swagger.version</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>$swagger.version</version>
</dependency>

其中版本最常用2.9.2

二、在spring启动类添加注解@EnableSwagger2

@EnableSwagger2是springfox提供的一个注解，代表swagger2相关技术开启。会扫描当前类所在包，及子包中所有类型的swagger相关注解，做swagger文档的定制

三、启动项目，查看swaggerui.html界面

这是我开发项目的地址，访问后可以看到swaggerui.html

http://localhost:9527/swagger-ui.html

点击try it out可以输入对应的参数查看返回结果

四，编写SwaggerConfig配置文件

@EnableSwagger2
@Configuration
public class SwaggerConfig 
    @Autowired
    private ApplicationContext applicationContext;

    private Contact contact = new Contact("NIUA","localhost:8080/swagger-ui.html", "1053288979@qq.com");

    @Bean
    public Docket createRestApi() 
        ServletContext servletContext = applicationContext.getBean(ServletContext.class);
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(Predicates.not(regex("/error.*")))
                .build()
                .apiInfo(apiInfo());
    



    private ApiInfo apiInfo() 
        return new ApiInfoBuilder()
                .title("平台接口 v1.0")
                .description("平台接口")
                .contact(contact)
                .version("1.0")
                .build();

@Bean
    public Docket createRestApi() 
        ServletContext servletContext = applicationContext.getBean(ServletContext.class);
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(Predicates.not(regex("/error.*")))
                .build()
                .apiInfo(apiInfo());

创建Docker类型的对象，并使用spring容器管理。Docker是Swagger中的全局配置对象

DocumentationType.SWAGGER_2：给Docket一个类对象，知道是那一个版本的

apiInfo()：API文档的描述信息，参数是一个ApiInfo类对象，使用bulid()构建器来创建
private ApiInfo apiInfo() 
       return new ApiInfoBuilder()
               .title("平台接口 v1.0")
               .description("平台接口")
               .contact(contact)
               .version("1.0")
               .build();
   
contact()：配置swagger文档的主体内容，里面填写也是一个类对象，类对象最多可以三个参数，发布者名称，文档发布者的网站url地址（企业网站），文档发布者的电子邮箱地址
private Contact contact = new Contact("NIUA","localhost:8080/swagger-ui.html", "1053288979@qq.com");
title()：标题 description()：描述信息 .version()：版本信息

对应如下内容
select()：获取Docker中的选择器，返回ApiSelectorBuilder。构建选择器。如扫描什么包的注解

apis()：后面是RequestHandlerSelectors的类下的(Predicate)规则，规定扫描那些包的注解，默认是启动类及其子包下的注解
RequestHandlerSelectors类下有几个静态方法（举例三个）

basePackage()：后面填写包名的具体地址，会扫描改包及其子包的注解
docker.apis(RequestHandlerSelectors.basePackage("com.xxx"))
any()：为任何接口生成API文档

none()：任何接口都不生成接口文档
path()：使用正则表达式，约束生成Api文档的路径地址，后面填写过滤（通过）的路径
//过滤掉admin路径下的所有页面
.paths(Predicates.not(PathSelectors.regex("/admin/.*")))
//过滤掉所有error或error.*页面
.paths(Predicates.not(PathSelectors.regex("/error.*")))

//所有error或error.*页面或者admin路径下的所有页面都支持（or任意满足起一就通过）
.paths(Predicates.or(PathSelectors.regex("/error.*"),PathSelectors.regex("/admin/.*")))

五：Swagger支持自定义注解

这里没有提及，感兴趣可以自己搜索（留个位置，日后用到了补充）

六：Swagger2常用注解

@Api(常用)

作用：@Api是类上注解。控制整个类生成接口信息的内容

属性：

tags：类的名称。可以有多个值，多个值表示多个副本（别名），有几个别名在swaggerui视图上显示几个控制器访问菜单

description：描述，已过时

@ApiOperation

作用：@ApiOperation是方法上注解，描述方法的相关消息

属性：

value：方法描述作用

notes：方法笔记（展开描述）

@ApiParm

作用：@ApiParm是方法参数的注解。描述该参数

属性：

name：参数名称

value：描述参数作用

required：值为boolean类型，表示该参数是否为必要参数，默认为false

@ApiIgnore

作用：@ApiParm是方法或者参数的注解。忽略注解的方法或者参数，不生成帮助文档

@ApiImplicitParam(常用)

作用：@ApiParm是作用于类上方法，用来描述方法参数的注解。

属性：

name：参数名称，和方法的参数一致

value：参数具体描述

required：值为boolean类型，表示该参数是否为必要参数，默认为false

paramType：参数类型
paramType="字符串"
paramType = "header"
dataType：数据类型
dataType = "string"  //字符串数据
dataType = "键值对" 

@ApiImplicitParams

后面跟@ApiImplicitParam的集合，一般用于多个参数的描述

@ApiImplicitParams(@ApiImplicitParam(name = "Authorization", value = "Authorization token", required = true, dataType = "string", paramType = "header"))

@ApiModel(常用)

作用：@ApiModel是作用于实体类上，描述一个实体类型，整个实体类型如果成为任何一个生成api帮助文档的返回对象的时候，该注解被解析

属性：

value：实体类名称

description：实体类描述

@ApiModelProperty(常用)

作用：@ApiModel是作用于实体类的属性上，描述实体类属性

属性：

value：实体属性描述

name：实体类属性名字，与属性名一致

在我的 Springboot 项目中添加 swagger3 后无法将应用程序名称添加到基本 URL

【中文标题】在我的 Springboot 项目中添加 swagger3 后无法将应用程序名称添加到基本 URL【英文标题】：Unable to add application name to base URL after adding swagger3 in my Springboot project 【发布时间】：2021-12-11 02:19:57 【问题描述】：

当我使用 springfox-swagger 2.9.0 时，我在我的项目中使用了以下代码。

 @Configuration
    @EnableSwagger2
    public class SwaggerConfig 
    
        @Bean
        public Docket api() 
        Docket docket = null;
    try
     if(!(profile.contains("local")|| (profile.contains("test"))
            docket = new Docket(DocumentationType.SWAGGER_2)
    .host(host)
    .pathProvider(new RelativePathProvider(servletContext)
    @Override
    public String getApplicationBasePath()
    
    return "/api";
    
    )
    .select()
    .apis(RequestHandlerSelectors.basePackage("org.app.controller"))
    .paths(PathSelectors.any())
    .build();
        
    else
    docket = new Docket(DocumentationType.SWAGGER_2)
    .host(host)
    .select()
    .apis(RequestHandlerSelectors.basePackage("org.app.controller"))
    .paths(PathSelectors.any())
    .build();
    
    
    catch(Exception e)
    logger.info("Unable to return docket",ex)
    
    return docket;

添加以下 swagger 3.0.0 依赖后，我更新的类是：

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



@Configuration
public class SwaggerConfig 

    @Bean
    public Docket api() 
    Docket docket = null;
try
 if(!(profile.contains("local")|| (profile.contains("test"))
        docket = new Docket(DocumentationType.SWAGGER_2)
.host(host)
.pathProvider(new PathProvider()
@Override
public String getOperationPath(String operationPath)
return operationPath.replace("/api","");


@Override
public String getResourceListingPath(String groupName, String apiDeclaration)
return null;

)
.select()
.apis(RequestHandlerSelectors.basePackage("org.app.controller"))
.paths(PathSelectors.any())
.build();
    
else
docket = new Docket(DocumentationType.SWAGGER_2)
.host(host)
.select()
.apis(RequestHandlerSelectors.basePackage("org.app.controller"))
.paths(PathSelectors.any())
.build();


catch(Exception e)
logger.info("Unable to return docket",ex)

return docket;

使用此代码后，我无法从更新的 swagger url 将“/api”附加到我的 baseurl“localhost:8080”。 http://localhost:8080/abc-api/swagger-ui/index.html#/

基本网址应显示为“localhost:8080/api”。

我尝试为 PathProvider 实现创建单独的 bean，然后传入参数，但仍然存在同样的问题。

谁能告诉我我在这里做错了什么以及如何将baseurl创建为“/api”或“/”？

【问题讨论】：

【参考方案1】：

这不是您问题的答案，但它可能对您有所帮助。由于无论如何您都在迁移，请考虑使用 springdoc 而不是 Springfox。它是一个较新的库，比 Springfox 更易于使用且不易出错。我们在 2 年前搬到这里，我们很高兴我们做到了。网上有很好的文档和教程：

https://springdoc.org/ https://www.baeldung.com/spring-rest-openapi-documentation

它也非常活跃，您通常会在github page 上很快得到解答。

【讨论】：

根据公司标准，必须仅在我的项目中使用 springfox。我不能简单地改变图书馆。所以寻找任何与springfox-swagger库相关的解决方案很公平 ;) 如果你能改变它，将来考虑springdoc。

以上是关于SpringBoot项目中使用Swagger2及注解解释（详细）的主要内容，如果未能解决你的问题，请参考以下文章

SpringBoot项目集成Swagger2

SpringBoot使用Swagger2实现Restful API

SpringBoot项目使用Swagger2(丝袜哥)实现接口测试管理

SpringBoot中优雅的使用Swagger2

SpringBoot项目中使用swagger2暴露resftul接口增加JWT来进行安全性验证

springboot 集成swagger2