Swagger
1 swagger运行
引用至: https://blog.csdn.net/sanyaoxu_2/article/details/80555328
导入相应的依赖
<!--swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
在Config包底下创建Swagger2
@Configuration
@EnableSwagger2
public class Swagger2 {
/**
* 创建API应用
* apiInfo() 增加API相关信息
* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,
* 本例采用指定扫描的包路径来定义指定要建立API的目录。
*
* @return
*/
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.controller"))
.paths(PathSelectors.any())
.build();
}
/**
* 创建该API的基本信息(这些基本信息会展现在文档页面中)
* 访问地址:http://项目实际地址/swagger-ui.html
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("更多请关注http://www.baidu.com")
.termsOfServiceUrl("http://www.baidu.com")
.contact("sunf")
.version("1.0")
.build();
}
}
.apis(RequestHandlerSelectors.basePackage(“com.controller.HelloController”)): 注意 这里说明的是Controller包的位置, 不是Controller类的全类名
相应的Controller
@Controller
@RequestMapping("/say")
@Api(value = "SayController | 一个用来测试swagger注解的控制器")
public class HelloController {
@ResponseBody
@RequestMapping(value ="/getUserName", method= RequestMethod.GET)
@ApiOperation(value="根据用户编号获取用户姓名", notes="test: 仅1和2有正确返回")
@ApiImplicitParam(paramType="query", name = "userNumber", value = "用户编号", required = true, dataType = "Integer")
public String getUserName(@RequestParam Integer userNumber){
if(userNumber == 1){
return "张三丰";
}
else if(userNumber == 2){
return "慕容复";
}
else{
return "未知";
}
}
@ResponseBody
@RequestMapping("/updatePassword")
@ApiOperation(value="修改用户密码", notes="根据用户id修改密码")
@ApiImplicitParams({
@ApiImplicitParam(paramType="query", name = "userId", value = "用户ID", required = true, dataType = "Integer"),
@ApiImplicitParam(paramType="query", name = "password", value = "旧密码", required = true, dataType = "String"),
@ApiImplicitParam(paramType="query", name = "newPassword", value = "新密码", required = true, dataType = "String")
})
public String updatePassword(@RequestParam(value="userId") Integer userId, @RequestParam(value="password") String password,
@RequestParam(value="newPassword") String newPassword){
if(userId <= 0 || userId > 2){
return "未知的用户";
}
if(StringUtils.isEmpty(password) || StringUtils.isEmpty(newPassword)){
return "密码不能为空";
}
if(password.equals(newPassword)){
return "新旧密码不能相同";
}
return "密码修改成功!";
}
}
完成上述代码添加上,启动Spring Boot程序,访问:
http://localhost:8080/swagger-ui.html
@Api:用在类上,说明该类的作用。
@ApiOperation:注解来给API增加方法说明。
@ApiImplicitParams : 用在方法上包含一组参数说明。
@ApiImplicitParam:用来注解来给方法入参增加说明。
参数:
·paramType:指定参数放在哪个地方
··header:请求参数放置于Request Header,使用@RequestHeader获取
··query:请求参数放置于请求地址,使用@RequestParam获取
··path:(用于restful接口)-->请求参数的获取:@PathVariable
··body:(不常用)
··form(不常用)
·name:参数名
·dataType:参数类型
·required:参数是否必须传(true | false)
·value:说明参数的意思
·defaultValue:参数的默认值
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
——code:数字,例如400
——message:信息,例如"请求参数异常!"
——response:抛出异常的类
@ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:描述一个model的属性
2 每一步分析
首先在config类上标注@Configuration
然后加上@EnableSwagger2
#
1.1 @Configuration的作用
是一个接口
指示一个类声明一个或者多个@Bean 声明的方法并且由Spring容器统一管理
一看到这个注解,我们最浅显的理解就是 这个是取代Spring中的xml配置的。
在类上面标注了@Configuration 指明这是一个Spring的配置文件。
在Spring中我们通过添加@Bean到方法体上。
把它注入到Spring容器中。
1.2 @EnableSwagger2的作用
通过Bean把Docket注入到Spring的容器中。
1.3 比较好奇Docket是干嘛的? 为什么要用它?
Docket : 摘要,记事表
进入Docket类中查看源码
有一个有参构造器,形参是文件类型DocumentationType
打开DocumentationType类,继承SimplePluginMatadata(简易插件数据)
在这个类中,有有参构造器,其中是插件的名字和版本。
1.3.1 API指的是什么?
api 根据英文解释就是 java application interface 应用程序接口
其后有.apiInfo() 调用方法apiInfo 接口信息输入
查看一下
在当前类的方法下面我们自己写上apiInfo 信息录入。
添加标题,描述,版本等等,最后在建立。
.select() 选择 程序接口建立(当前Docket)
.apis(RequestHandlerSelectors.basePackage(“com.controller.HelloController”))
.apis() : 指定所有的接口,告诉明确的路径 请求处理器选择.包名为 “XXX”
.paths(PathSelectors.any())
.paths(): 指定路径
.build(); 然后建立。
1.4 为什么每次在@Configuration中写入Bean都是放回一个实例对象?
上一篇: Swagger
下一篇: swagger使用说明
推荐阅读
-
从零开始搭建前后端分离的NetCore2.2(EF Core CodeFirst+Autofac)+Vue的项目框架之十一Swagger使用一
-
Asp.net core WebApi 使用Swagger生成帮助页实例
-
在Spring Boot中使用swagger-bootstrap-ui的方法
-
在ASP.NET Core 3.0中使用Swagger
-
c# webapi结合swagger的使用
-
asp.net core 一个中小型项目实战的起手式——Swagger配置
-
.net core webapi 文件上传在 Swagger 文档中的有好提示处理
-
十、Spring boot 简单优雅的整合 Swagger2
-
[springboot 开发单体web shop] 4. Swagger生成Javadoc
-
asp.net core 3.0 中使用 swagger