我的编程空间,编程开发者的网络收藏夹
学习永远不晚

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

短信预约 -IT技能 免费直播动态提醒
省份

北京

  • 北京
  • 上海
  • 天津
  • 重庆
  • 河北
  • 山东
  • 辽宁
  • 黑龙江
  • 吉林
  • 甘肃
  • 青海
  • 河南
  • 江苏
  • 湖北
  • 湖南
  • 江西
  • 浙江
  • 广东
  • 云南
  • 福建
  • 海南
  • 山西
  • 四川
  • 陕西
  • 贵州
  • 安徽
  • 广西
  • 内蒙
  • 西藏
  • 新疆
  • 宁夏
  • 兵团
手机号立即预约

请填写图片验证码后获取短信验证码

看不清楚,换张图片

免费获取短信验证码

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常用注解相关介绍。

仅为个人经验,希望能给大家一个参考,也希望大家多多支持编程网。

免责声明:

① 本站未注明“稿件来源”的信息均来自网络整理。其文字、图片和音视频稿件的所属权归原作者所有。本站收集整理出于非商业性的教育和科研之目的,并不意味着本站赞同其观点或证实其内容的真实性。仅作为临时的测试数据,供内部测试之用。本站并未授权任何人以任何方式主动获取本站任何信息。

② 本站未注明“稿件来源”的临时测试数据将在测试完成后最终做删除处理。有问题或投稿请发送至: 邮箱/279061341@qq.com QQ/279061341

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

下载Word文档到电脑,方便收藏和打印~

下载Word文档

猜你喜欢

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

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

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

本篇内容介绍了“SpringBoot项目集成Swagger和swagger-bootstrap-ui及常用注解有哪些”的有关知识,在实际案例的操作过程中,不少人都会遇到这样的困境,接下来就让小编带领大家学习一下如何处理这些情况吧!希望大家仔
2023-07-05

编程热搜

  • Python 学习之路 - Python
    一、安装Python34Windows在Python官网(https://www.python.org/downloads/)下载安装包并安装。Python的默认安装路径是:C:\Python34配置环境变量:【右键计算机】--》【属性】-
    Python 学习之路 - Python
  • chatgpt的中文全称是什么
    chatgpt的中文全称是生成型预训练变换模型。ChatGPT是什么ChatGPT是美国人工智能研究实验室OpenAI开发的一种全新聊天机器人模型,它能够通过学习和理解人类的语言来进行对话,还能根据聊天的上下文进行互动,并协助人类完成一系列
    chatgpt的中文全称是什么
  • C/C++中extern函数使用详解
  • C/C++可变参数的使用
    可变参数的使用方法远远不止以下几种,不过在C,C++中使用可变参数时要小心,在使用printf()等函数时传入的参数个数一定不能比前面的格式化字符串中的’%’符号个数少,否则会产生访问越界,运气不好的话还会导致程序崩溃
    C/C++可变参数的使用
  • css样式文件该放在哪里
  • php中数组下标必须是连续的吗
  • Python 3 教程
    Python 3 教程 Python 的 3.0 版本,常被称为 Python 3000,或简称 Py3k。相对于 Python 的早期版本,这是一个较大的升级。为了不带入过多的累赘,Python 3.0 在设计的时候没有考虑向下兼容。 Python
    Python 3 教程
  • Python pip包管理
    一、前言    在Python中, 安装第三方模块是通过 setuptools 这个工具完成的。 Python有两个封装了 setuptools的包管理工具: easy_install  和  pip , 目前官方推荐使用 pip。    
    Python pip包管理
  • ubuntu如何重新编译内核
  • 改善Java代码之慎用java动态编译

目录