首页  >  文章  >  Java  >  SpringBoot项目中怎么使用Swagger2及注解解释

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

WBOY
WBOY转载
2023-05-17 09:40:381107浏览

    一、导入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

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

    springfox提供的@EnableSwagger2注解可以启用swagger2相关技术。该程序将遍历当前类所在的包及其子包中的所有类型,以查找与Swagger相关的注解,并定制Swagger文档

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

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

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

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

    点击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():版本信息

    对应如下内容

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

    返回ApiSelectorBuilder的方法是select(),用于获取Docker中的选择器。构建选择器。如扫描什么包的注解

    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:描述,已过时

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

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

    @ApiOperation

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

    属性

    value:方法描述作用

    notes:方法笔记(展开描述)

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

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

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

    @ApiParm

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

    属性

    name:参数名称

    value:描述参数作用

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

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

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

    @ApiIgnore

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

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

    @ApiImplicitParam(常用)

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

    属性

    name:参数名称,和方法的参数一致

    value:参数具体描述

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

    paramType:参数类型

    paramType="字符串"
    paramType = "header"

    dataType:数据类型

    dataType = "string"  //字符串数据
    dataType = "键值对"

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

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

    @ApiImplicitParams

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

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

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

    @ApiModel(常用)

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

    属性

    value:实体类名称

    description:实体类描述

    @ApiModelProperty(常用)

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

    属性

    value:实体属性描述

    name:实体类属性名字,与属性名一致

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

    以上是SpringBoot项目中怎么使用Swagger2及注解解释的详细内容。更多信息请关注PHP中文网其他相关文章!

    声明:
    本文转载于:yisu.com。如有侵权,请联系admin@php.cn删除