springboot2.x集成swagger的方法示例

springboot2.x集成swagger的方法示例

集成swagger

pom包配置

io.springfox

springfox-swagger2

2.9.2

io.springfox

springfox-swagger-ui

${swagger.version}

添加Swagger配置文件

@Configuration

@EnableSwagger2

public class SwaggerConfig {

/**

* 创建一个Docket对象

* 调用select()方法，

* 生成ApiSelectorBuilder对象实例，该对象负责定义外漏的API入口

* 通过使用RequestHandlerSelectors和PathSelectors来提供Predicate，在此我们使用any()方法，将所有API都通过Swagger进行文档管理

* @return

*/

@Bean

public Docket createRestApi() {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())

.select()

.apis(RequestHandlerSelectors.any())

.paths(PathSelectors.any())

.build();

}

private ApiInfo apiInfo() {

retKbgOsMhJurn new ApiInfoBuilder()

//标题

.title("Spring Boot中使用Swagger2构建RESTful APIs")

//简介

.description("")

//服务条款

.termsOfServiceUrl("")

.contact(new Contact("chenguoyu","","chenguoyu_sir@163.com"))

//版本

.version("1.0")

.build();

}

}

如果不想将所有的接口都通过swagger管理的话，可以将RequestHandlerSelectors.any()修改为RequestHandlerSelectors.basePackage()

配置静态访问资源

@Configuration

public class WebMvcConfig implements WebMvcConfigurer {

@Override

public void addResourceHandlers(ResourceHandlerRegistry registry) {

// 解决 swagger-ui.html 404报错

registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");

}

}

到这里为止swagger就已经配置完了，可以启动项目，然后访问如下链接即可http://localhost:9000/swagger...

端口号applicationContext中设置的端口号。

集成swagger-bootstrap-ui

由于个人感觉原生的swagger-ui不太好看，网上提供了swagger-bootstrap-ui。

pom依赖

com.github.xiaoymin

swagger-bootstrap-ui

1.9.3

配置静态访问资源

@Configuration

public class WebMvcConfig implements WebMvcConfigurer {

@Override

public void addResourceHandlers(ResourceHandlerRegistry registry) {

// 解决 swagger-ui.html 404报错

registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");

// 解决 doc.html 404 报错

registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");

}

}

这时只需要访问以下链接即可http://localhost:9000/doc.html

swagger常用注解

@Api：用在类上，标志此类是Swagger资源

属性名称

备注

value

该参数没什么意义，在UI界面上不显示，所以不用配置

tags

说明该类的作用，参数是个数组，可以填多个

description

对api资源的描述

@ApiOperation：用在方法上，描述方法的作用

属性名称

备注

value

方法的用途和作用

tags

方法的标签，可以设置多个值

notes

方法的注意事项和备注

response

返回的类型（尽量不写，由swagger扫描生成）

@ApiImplicitParams：包装器：包含多个ApiImplicitParam对象列表

属性名称

备注

value

多个ApiImplicitParam配置

@ApiParam：用于Controller中方法的参数说明

属性名称

备注

name

属性名称

value

属性值

defaultValue

默认属性值

http://

allowableValues

可以不配置

required

是否属性必填

allowMultiple

文件上传时，是否允许多文件上传

@ApiImplicitParam：定义在@ApiImplicitParams注解中，定义单个参数详细信息，如果只有一个参数，也可以定义在方法上

属性名称

备注

name

参数名

value

参数说明

dataType

参数类型

paramType

表示参数放在哪里

header : 请求参数的获取：@RequestHeader

query : 请求参数的获取：@RequestParam

path : 请求参数的获取：@PathVariable

body : 不常用

form : 不常用

defaultValue

参数的默认值

required

参数是否必须传

@ApiModel：用在类上，表示对类进行说明，用于实体类中的参数接收说明

属性名称

备注

value

默认为类的名称

description

对该类的描述

@ApiModelProperty：在model类的属性添加属性说明

属性名称

备注

value

属性描述

name

属性名称

allowableValues

参数允许的值

dataType

数据类型

required

是否必填

@ApiResponses：包装器：包含多个ApiResponse对象列表

属性名称

备注

value

多个ApiResponse配置

@ApiResponse：定义在@ApiResponses注解中，一般用于描述一个错误的响应信息

属性名称

备注

code

响应码

message

状态码对应的响应信息

response

默认响应类 Void

responseContainer

参考ApiOperation中配置

@ApiIgnore()：用于类或者方法上，不被显示在页面上

总结

除上面之外有点值得注意的是，如果是上传文件的话，需要把@ApiImplicitParam中的dataType属性配置为__File否则在swagger中会显示为文本框而不是上传按钮

如果需要项目代码，可以去我的github中下载；具体代码可以查看swagger目录

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。