SpringBoot项目集成Swagger和swagger-bootstrap-ui及常用注解解读

更新时间：2023年03月31日 16:51:09 作者：Yuhei001

这篇文章主要介绍了SpringBoot项目集成Swagger和swagger-bootstrap-ui及常用注解解读，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教

一、前言

随着互联网项目前后端分离方式的流行，前端与后端交给不同的人员开发，项目沟通成本也随之提高。

主要表现在WebAPI接口的沟通，Swagger2 应运而生，它可以动态生成Api接口文档，降低沟通成本，促进项目高效开发。

下面讨论Swagger2及swagger-bootstrap-ui在SpringBoot上的集成

二、SpringBoot项目集成swagger

1. 引入依赖

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

2. 编写配置文件

可对照进行相应的修改

@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
@Profile({"dev","test"})
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("") //指定分组，对应(/v2/api-docs?group=)
                .pathMapping("") //base地址，最终会拼接Controller中的地址
                .apiInfo(apiInfo())
                .select()
                //为当前包路径
				// .apis(RequestHandlerSelectors.any())
                .apis(RequestHandlerSelectors.basePackage("com.riskeys.sd.custom"))
                .paths(PathSelectors.any())
                .build();
    }

    //构建 api文档的详细信息函数
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("XXX API对接文档")
                .description("XX API对接文档") //描述
                //创建人
                .contact(new Contact("yuhei001", "https://blog.csdn.net/Yuhei0", "18616591658@163.com"))
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
}

3. 启动访问页面

http://127.0.0.1:10086/swagger-ui.html

在这里插入图片描述

三、SpringBoot项目集成swagger-bootstrap-ui

在步骤二的基础上进行如下操作

1.引入依赖

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

2.配置资源处理规则

未配置的情况下，有可能访问报error.9996。

实现WebMvcConfigurer接口，或者WebMvcConfigurationSupport(老版的SpringBoot)，实现addResourceHandlers方法，加上如下所示代码即可。

@Configuration
public class AppWebConfig extends WebMvcConfigurationSupport{

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        // 解决 doc.html 404 报错
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

或者

@Configuration
public class AppWebConfig extends WebMvcConfigurationSupport{
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        // 解决 doc.html 404 报错
        registry.addResourceHandler("doc.html").addResourceLocations("classpath*:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath*:/META-INF/resources/webjars/");
    }
}

另外，也可以在启动类上进行实现重写

@SpringBootApplication
public class XXXApplication  implements WebMvcConfigurer{
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html").addResourceLocations("classpath*:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath*:/META-INF/resources/webjars/");
    }
}

3.启动访问页面

访问http://127.0.0.1:10086/doc.html，相较swagger-ui.html来说，此文档更为清爽。

在这里插入图片描述

四、Swagger常用注解介绍

swagger通过注解生成接口文档，包括接口名、请求方法、参数、返回信息等等。

1.Swagger2Config中相关swagger注解

1.1 @EnableSwagger2 开启Swagger

作用于配置类或启动类

1.2 @EnableSwaggerBootstrapUI 开启SwaggerBootstrapUi增强功能

作用于配置类或启动类，如果不使用增强功能，可不开启。

2.controller中相关swagger注解

2.1 @Api：修饰整个类，描述Controller的作用

value和tags均为说明，可用tags代替value

@Api(value = "保险公司列表查询", tags = {"保险公司列表查询"})

2.2 @ApiOperation() 用于方法；表示一个http请求的操作

@ApiOperation(value = "信息员保存(注册)/更新", tags = {"信息員保存"}, notes = "messenger desc")

2.3 @ApiParam 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）

适用于单个参数

@ApiParam(name="sdMessengerInfo",value="参数描述",required=true)

2.4 请求参数注解，可进行组合

@ApiImplicitParams 用于方法，包含多个 @ApiImplicitParam
@ApiImplicitParam 用于方法，表示单独的请求参数

适用于对多个参数进行描述

示例：

// 组合使用
@ApiImplicitParams ({
    @ApiImplicitParam(name = "id", value = "参数中文描述", required = true)
})
// 单独使用
@ApiImplicitParam(paramType="query", name="id", dataType="String", required=true, value="参数描述")

注意，当同时存在@ApiParam和@ApiImplicitParam时，以@ApiImplicitParam的描述为准。

2.5 @ApiIgnore() 用于类或者方法上，可以不被swagger显示在页面上 ,使用较少。

2.6 响应配置

@ApiResponses
@ApiResponse

// 单独配置
@ApiResponse(code = 400, message = "Invalid user supplied")
// 组合使用
@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })

2.7 @ResponseHeader 响应头设置

@ResponseHeader(name="head1",description="response head conf")

3.Model中相关swagger注解

3.1 @ApiModel 用于类；表示对类进行说明，用于参数用实体类接收。

@ApiModel(value = "demo", description = "对象描述")

一般value和desc可以省略不写

3.2 @ApiModelProperty 用于方法，字段；表示对model属性的说明或者数据操作更改

@ApiModelProperty(value = "用户id",name = "openid2",dataType = "String", required = true, hidden = true)

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

一般只对value，required进行标示。

总结

以上，即为SpringBoot集成Swagger、swagger-bootstrap-ui以及Swagger常用注解相关介绍。

仅为个人经验，希望能给大家一个参考，也希望大家多多支持脚本之家。

您可能感兴趣的文章:

Jmeter结构体系及运行原理顺序解析
这篇文章主要介绍了Jmeter结构体系及运行原理顺序解析,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
2020-09-09
Java注解Annotaton详解
Java 注解（Annotation）又称 Java 标注，是 JDK5.0 引入的一种注释机制，文中给大家介绍了三种基本的Annotaton，本文给大家介绍的非常详细，对大家的学习或工作具有一定的参考借鉴价值，需要的朋友参考下吧
2022-05-05
Java关键字synchronized基本使用详解
这篇文章主要给大家介绍了关于Java关键字synchronized基本使用的相关资料,synchronized可以用来同步静态和非静态方法,文中通过代码介绍的非常详细,需要的朋友可以参考下
2024-01-01
精通Java List 按字段提取对象
这篇文章主要介绍了精通Java List 按字段提取对象的相关资料,需要的朋友可以参考下
2023-11-11
利用Thumbnailator轻松实现图片缩放、旋转与加水印
java开发中经常遇到对图片的处理，JDK中也提供了对应的工具类，不过处理起来很麻烦，Thumbnailator是一个优秀的图片处理的开源Java类库,处理效果远比Java API的好，这篇文章主要介绍了利用Thumbnailator如何轻松的实现图片缩放、旋转与加水印，需要的朋友可以参考下
2017-01-01
Java中实现多线程的几种方式总结
文章介绍了三种创建线程的方式：继承Thread类、实现Runnable接口和实现Callable接口,并比较了它们之间的区别和优缺点
2025-01-01
maven配置文件pom增加变量取版本号方式
这篇文章主要介绍了maven配置文件pom增加变量取版本号方式，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教
2021-12-12
Spring Boot webflux使用方法解析
这篇文章主要介绍了Spring Boot webflux使用方法解析,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
2020-03-03
JavaWeb中文编码问题实例讲解
在本篇文章里小编给大家整理的是关于JavaWeb中文编码问题方法的相关知识点内容，需要的朋友们参考下
2019-09-09
Mybatis映射文件详解之mapper.xml文件
本文详细介绍了Mybatis映射文件的结构、标签和使用方法,包括mapper元素、标签的主要属性如id、parameterType、resultType以及动态SQL和结果映射的使用,通过映射文件,可以将数据库表与Java对象映射,支持查询、插入、更新、删除等操作,提高了SQL语句的灵活性和可重用性
2024-09-09