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函数的工作方式)。默认是服务器返回的顺序不变。
- Selenium2+python自动化47-判断弹出框存在(alert_is_present)
- Free Pascal初次体验(有亮点哦)
- HDU 1312 Red and Black(DFS,板子题,详解,零基础教你代码实现DFS)
- Selenium2+python自动化48-登录方法(参数化)
- 51Nod 1003 阶乘后面0的数量(数学,思维题)
- 如何查看某个用户指定时间段的ABAP开发记录
- Selenium2+python自动化49-判断文本(text_to_be_present_in_element)
- 洛谷 P1876 开灯(思维,枚举,规律题)
- 线性回归:简单线性回归详解
- Codeforces 789A Anastasia and pebbles(数学,思维题)
- hihoCoder #1082 : 然而沼跃鱼早就看穿了一切(字符串处理)
- 51Nod 1182 完美字符串(字符串处理 贪心 Facebook Hacker Cup选拔)
- 51Nod 1080 两个数的平方和(数论,经典题)
- Selenium3+python自动化50-环境搭建(firefox)
- java教程
- Java快速入门
- Java 开发环境配置
- Java基本语法
- Java 对象和类
- Java 基本数据类型
- Java 变量类型
- Java 修饰符
- Java 运算符
- Java 循环结构
- Java 分支结构
- Java Number类
- Java Character类
- Java String类
- Java StringBuffer和StringBuilder类
- Java 数组
- Java 日期时间
- Java 正则表达式
- Java 方法
- Java 流(Stream)、文件(File)和IO
- Java 异常处理
- Java 继承
- Java 重写(Override)与重载(Overload)
- Java 多态
- Java 抽象类
- Java 封装
- Java 接口
- Java 包(package)
- Java 数据结构
- Java 集合框架
- Java 泛型
- Java 序列化
- Java 网络编程
- Java 发送邮件
- Java 多线程编程
- Java Applet基础
- Java 文档注释
- Theme preview
- “抽象类”到底抽不抽象?实例对比一看便知!
- C#索引器的实现、索引器和属性的异同对比,这些技能你get到了嘛?
- 我竟然用它搞懂了王者荣耀的技能释放机制!【C#委托】
- 使用docker-compose 搭建 lnmp
- Java接口也有坑?不容忽视!
- 值得练手的JavaGUI项目——色彩调节器的实现【附完整源码】
- 自定义短标签
- Python简单又好玩的项目推荐!【持续更新】
- 使用 JsDelivr作为CDN 加速服务
- Java利用TCP协议实现客户端与服务器通信【附通信源码】
- 增加标签云代替原有标签和分类效果
- 新增搜索功能
- 利用实例巧妙区分“抽象方法”和“虚方法”!
- windows 右键菜单的添加和移除