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

image-20220813204858495

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

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

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

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

image-20220813205239054

image-20220813205539273

image-20220813212309718

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

对应如下内容

image-20220813230037907

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

image-20220814000708784

image-20220814000715865

@ApiOperation

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

属性

value:方法描述作用

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

image-20220814001227958

image-20220814001241700

image-20220814001436901

@ApiParm

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

属性

name:参数名称

value:描述参数作用

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

image-20220814001817020

image-20220814001843282

@ApiIgnore

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

image-20220814002442974

@ApiImplicitParam(常用)

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

属性

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

value:参数具体描述

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

paramType:参数类型

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

dataType:数据类型

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

image-20220814002923516

image-20220814002946956

@ApiImplicitParams

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

image-20220814003200310

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

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

属性

value:实体类名称

description:实体类描述

@ApiModelProperty(常用)

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

属性

value:实体属性描述

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

image-20220814003816105

Logo

华为云1024程序员节送福利,参与活动赢单人4000元礼包,更有热门技术干货免费学习

更多推荐