swagger3设置值可以为空_Swagger3使用

swagger是干嘛的不是本说明介绍的内容&＃xff0c;请自行百度。

本说明旨在快速上手使用swagger生成接口文档&＃xff0c;swagger3真香&＃xff01;&＃xff01;&＃xff01;

一、依赖

添加依赖和spring-boot-starter-parent的版本有关&＃xff0c;自动引入的spring-plugin-core包版本不一致会导致项目跑不起来&＃xff0c;这里是个大坑。

1.1、2.1.x版本

io.springfox

springfox-boot-starter

3.0.0

spring-plugin-core

org.springframework.plugin

org.springframework.plugin

spring-plugin-core

2.0.0.RELEASE

1.2、2.3.x版本

io.springfox

springfox-boot-starter

3.0.0

二、配置

2.1、启动类

启动类添加&＃64;EnableOpenApi注解&＃xff0c;然并卵&＃xff0c;经过测试不加也可以(黑人问号脸.jpg)&＃xff0c;到底加还是不加&＃xff0c;看你心情吧。

&＃64;EnableOpenApi

&＃64;SpringBootApplication

public class Swagger3DemoApplication {

public static void main(String[] args) {

SpringApplication.run(Swagger3DemoApplication.class, args);

}

}

2.2、swagger配置

可以根据Environment和Profiles对象来控制不同环境文档地址是否对外暴漏

&＃64;Configuration

public class SwaggerConfig {

&＃64;Bean

public Docket initDocket(Environment env) {

//设置要暴漏接口文档的配置环境

Profiles profile &＃61; Profiles.of("dev", "test");

boolean flag &＃61; env.acceptsProfiles(profile);

return new Docket(DocumentationType.OAS_30)

.apiInfo(apiInfo())

.enable(flag)

.select()

.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))

.paths(PathSelectors.any())

.build();

}

private ApiInfo apiInfo() {

return new ApiInfoBuilder()

.title("Swagger3-Demo接口文档")

.description("技术支持-云嘉健康技术团队")

.contact(new Contact("云嘉健康技术团队", "http://www.yunjiacloud.com", "duchong&＃64;yunjiacloud.com "))

.version("1.0")

.build();

}

}

三、常用注解

3.1、类

&＃64;Api()&＃xff1a;表示这个类是 swagger 资源

tags&＃xff1a;表示说明内容&＃xff0c;只写 tags 就可以省略属性名

value&＃xff1a;同样是说明&＃xff0c;不过会被 tags 替代&＃xff0c;没卵用

3.2、方法上

&＃64;ApiOperation() &＃xff1a;对方法的说明&＃xff0c;注解位于方法上

value&＃xff1a;方法的说明

notes&＃xff1a;额外注释说明

response&＃xff1a;返回的对象

tags&＃xff1a;这个方法会被单独摘出来&＃xff0c;重新分组&＃xff0c;若没有&＃xff0c;所有的方法会在一个Controller分组下

3.3、方法入参

&＃64;ApiParam()&＃xff1a;对方法参数的具体说明&＃xff0c;用在方法入参括号里&＃xff0c;该注解在post请求参数时&＃xff0c;参数名不显示

name&＃xff1a;参数名

value&＃xff1a;参数说明

required&＃xff1a;是否必填

&＃64;ApiImplicitParam对方法参数的具体说明&＃xff0c;用在方法上&＃64;ApiImplicitParams之内&＃xff0c;该注解在get,post请求参数时&＃xff0c;参数名均正常显示

name 参数名称

value 参数的简短描述

required 是否为必传参数

dataType 参数类型&＃xff0c;可以为类名&＃xff0c;也可以为基本类型(String&＃xff0c;int、boolean等)指定也不起作用&＃xff0c;没卵用

paramType 参数的传入(请求)类型&＃xff0c;可选的值有path, query, body, header or form。

3.4、实体

&＃64;ApiModel描述一个Model的信息(一般用在请求参数无法使用&＃64;ApiImplicitParam注解进行描述的时候)

value model的别名&＃xff0c;默认为类名

description model的详细描述

&＃64;ApiModelProperty描述一个model的属性

value 属性简短描述

example 属性的示例值

required 是否为必须值

3.5、header参数

&＃64;ApiImplicitParams({ &＃64;ApiImplicitParam(paramType&＃61;"header",name&＃61;"USERTOKEN",dataType&＃61;"String",required&＃61;true,value&＃61;"用户token")

})

3.6、file入参

需要使用&＃64;RequestPart 注解

&＃64;ApiOperation(value &＃61; "上传文件接口",notes &＃61; "上传文件接口")

&＃64;ApiImplicitParams({

&＃64;ApiImplicitParam(name &＃61; "name", value &＃61; "上传人")

})

&＃64;PostMapping(value &＃61; "/uploadFile")

public String uploadFile(&＃64;RequestParam("name") String name,&＃64;RequestPart("file") MultipartFile file){

}

四、拦截器放行

若项目中有使用拦截器&＃xff0c;放行以下路径

&＃64;Configuration

public class WebConfig implements WebMvcConfigurer {

&＃64;Autowired

TokenInterceptor tokenInterceptor;

/**

* 拦截器

* &＃64;param registry

*/

&＃64;Override

public void addInterceptors(InterceptorRegistry registry) {

// 注册token拦截器

registry.addInterceptor(tokenInterceptor)

.addPathPatterns("/**")

.excludePathPatterns("/**/swagger-ui/**")

.excludePathPatterns("/**/swagger-resources/**")

.excludePathPatterns("/**/v3/**")

;

}

}

五、文档访问地址

http://ip:port/context-path/swagger-ui/

http://ip:port/context-path/swagger-ui/index.html

六、统一返回值问题

若项目中使用了统一返回值的包装类例如BaseResponse&＃xff0c;方法返回时加上泛型&＃xff0c;

例如返回 BaseResponse

七、完整demo