开发者

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

开发者 https://www.devze.com 2023-04-01 10:38 出处:网络 作者: Yuhei001
目录一、前言二、SpringBoot项目集成swagger1. 引入依赖2. 编写配置文件3. 启动访问页面三、SpringBoot项目集成swagger-bootstrap-ui1.引入依赖2.配置资源处理规则3.启动访问页面四、Swagandroidger常用注解介绍1.Sw
目录
  • 一、前言
  • 二、SpringBoot项目集成swagger
    • 1. 引入依赖
    • 2. 编写配置文件
    • 3. 启动访问页面
  • 三、SpringBoot项目集成swagger-bootstrap-ui
    • 1.引入依赖
    • 2.配置资源处理规则
    • 3.启动访问页面
  • 四、Swagandroidger常用注解介绍
    • 1.Swagger2Config中相关swagger注解
    • 2.controller中相关swagger注解
    • 3.Model中相关swagger注解
  • 总结

    一、前言

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

    主要表现在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和swagger-bootstrap-ui及常用注解解读

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

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

    1.引入依赖

            <dependency>
                <groupId>com.github.xiaoymin</groupId>
                <artifactId>swagger-bootstrap-u开发者_Go教程i</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 regwww.devze.comistry) {
            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来说,此文档更为清爽。

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

    四、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中相关swa编程gger注解

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

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

    0

    精彩评论

    暂无评论...
    验证码 换一张
    取 消

    关注公众号