SpringMVC 中配置 Swagger 插件的教程(分享)
一、简介
Swagger的目标是为REST API定义一个与语言无关的标准接口,允许用户发现和理解计算机服务的功能,而无需访问源代码。当通过Swagger正确定义时,用户可以用最少量的实现逻辑理解远程服务并与之交互。类似于低级编程所做的接口。
二、实现步骤
1、添加 Maven 依赖
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency>
2、Swagger 配置类
@Configuration @EnableSwagger2 //@ComponentScan(basePackageClasses = JgBjBaseInfoCompanyApi.class) 或者 @ComponentScan(basePackages = "com.summersoft.ts.schedule.supervision.controller") //要扫描的包路径 public class SwaggerConfig { @Bean public Docket swaggerSpringMvcPlugin() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() //选择哪些路径和api会生成document .apis(RequestHandlerSelectors.any())//对所有Api进行监控 .paths(PathSelectors.any()) //对所有路径进行扫描 .build(); } /** * api具体信息 * * @return */ private ApiInfo apiInfo() { ApiInfo apiInfo = new ApiInfo( "对接服务平台API文档", //标题 "", //描述 "1.0", //版本 "", "", "", //签名 "" //签名链接 ); return apiInfo; } }
3、Swagger 注解
Swagger 会去扫描SwaggerConfig 中配置的包路径下的带有Swagger 注解的类文件,并最后生成一串扫描的Json文件...
Swagger 注解说明:https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel
@Api :用在类上,说明该类的作用,需要说明的是较老的版本用的value表示扫描生成的类名,1.5后要用tag 表示类名
@Api(tag= "UserController", description = "用户相关api")
@ApiOperation :用在方法上,说明方法的作用
@ApiOperation(value = "查找用户", notes = "查找用户", httpMethod = "GET", produces =
MediaType.APPLICATION_JSON_UTF8_VALUE)
@ApiParam :用在参数列表中,表明参数的含义
@ApiParam(value = "创建或更新距离当前时间(月)") Integer time
@ApiImplicitParams :用在方法上包含一组参数说明
@ApiImplicitParam :用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
paramType:参数放在哪个地方
header–>请求参数的获取:@RequestHeader
query–>请求参数的获取:@RequestParam
path(用于restful接口)–>请求参数的获取:@PathVariable
body(不常用)
form(不常用)
name:参数名
dataType:参数类型
required:参数是否必须传
value:参数的意思
defaultValue:参数的默认值
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "唯一id", required = true, dataType = "Long", paramType = "path"),
})
@ApiResponses :用于表示一组响应
@ApiResponse :用在@ApiResponses中,一般用于表达一个错误的响应信息
code:数字,例如400
message:信息,例如”请求参数没填好”
response:抛出异常的类
@ApiResponses(value = {
@ApiResponse(code = 400, message = "No Name Provided")
})
@ApiModel :描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModel(value = "用户实体类")
@ApiModelProperty :描述一个model的属性
@ApiModelProperty(value = "登录用户")
三、swagger-ui
有了上面的配置信息,Swagger 就会帮我们扫描出所有的 类信息,并生成一个JSON文件。想让JSON文件友好的展示在人们面前,需要用到 swagger-ui 这个组件:
1、 swagger-ui 使用说明:https://swagger.io/docs/swagger-tools/
2、下载 swagger-ui ,在webapp 目录下新建一个swagger目录,把 dist 目录下的文件,放入swagger目录下,并修改index.html文件,默认是从连接 http://petstore.swagger.io/v2/swagger.json 获取 API 的 JSON,这里需要将url值修改为 http://{ip}:{port}/{projectName}/api-docs的形式,{}中的值根据自身情况填写。
比如我的url值为:
http://localhost:8080/vouchers/api-docs 。另外,需要配置一下Spring MVC的资源放行:<mvc:resources mapping="/swagger/**" location="/swagger/"/>
tips:默认的dist 目录下没有这么多文件,swagger-ui 可以自定义配置,这个是我们项目中使用的,不用改项目名,项目名动态获取:https://files.cnblogs.com/files/jmcui/swagger.zip
3、swagger-ui 怎么对展示的接口排序:
apisSorter :对API /标签列表应用排序。它可以是'alpha'(按名称排序)或函数(请参阅Array.prototype.sort()以了解sort函数的工作原理)。默认是服务器返回的顺序不变。
operationsSorter :对每个API的操作列表应用一个排序。它可以是'alpha'(按字母数字排序),'method'(按HTTP方法排序)或函数(参见Array.prototype.sort()来知道sort函数的工作方式)。默认是服务器返回的顺序不变。
以上这篇SpringMVC 中配置 Swagger 插件的教程(分享)就是小编分享给大家的全部内容了,希望能给大家一个参考,也希望大家多多支持脚本之家。
相关文章
SpringBoot的@Value给静态变量注入application.properties属性值
这篇文章主要介绍了SpringBoot的@Value给静态变量注入application.properties属性值,Spring是一个开源的框架,主要是用来简化开发流程,通过IOC,依赖注入(DI)和面向接口实现松耦合,需要的朋友可以参考下2023-05-05解决Spring Security集成knife4j访问接口文档出现403的问题
这篇文章主要给大家介绍了如何解决Spring Security集成knife4j访问接口文档出现403的问题,文中有详细的解决方案,有需要的朋友可以参考阅读下2023-07-07jdk17 SpringBoot JPA集成多数据库的示例详解
这篇文章主要介绍了jdk17 SpringBoot JPA集成多数据库的示例代码,包括配置类、请求拦截器、线程上下文等相关知识,代码简单易懂,对大家的学习或工作具有一定的参考借鉴价值,需要的朋友可以参考下2023-08-08
最新评论