spring boot 学习笔记 - swagger

spring boot - swagger

​ 按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。

swagger 官网

一、环境依赖

//springfox-swagger2
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
//springfox-swagger-ui
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>

我在使用的时候，使用的是 `2.9.2` 版本,在使用的时候会报错`java.lang.NoClassDefFoundError:`,我添加了一个依赖得到解决

<dependency>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
<version>20.0</version>
</dependency>

二、配置

@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.xhb.swagger2.controller"))  // 为扫描包路径
.paths(PathSelectors.any())
.build();
}
/**
* api文档的详细信息函数,注意这里的注解引用的是哪个
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// //大标题
.title("财务系统 RESTful API")
// 版本号
.version("1.0")
// 描述
.description("API 描述")
//作者
//                .contact(new Contact("cashZhang", "https://blog.csdn.net/m0_37726449", "cashzhang27@qq.com"))
.build();
}
}

三、使用

1、常用标签

@Api()   用于类；
标识这个类是swagger的资源
　　tags–表示分组说明标签

@ApiOperation()   用于方法；
表示一个http请求的操作
　　value - 用于方法描述
　　notes - 用于提示内容

@ApiModel()   用于实体类
表示对类进行说明，用于参数用实体类接收
value – 表示对象名
description – 描述

@ApiModelProperty()   用于实体类字段
表示对model属性的说明或者数据操作更改
　　	value – 字段说明
　　	name – 重写属性名字
　　	dataType – 重写属性类型
　　	required – 是否必填
　　	example – 举例说明
　　	hidden – 隐藏

@ApiImplicitParam()    用于 controller 方法
表示单独的请求参数
　　	name – 参数ming
　	 value – 参数说明
　　	dataType – 数据类型
　　	paramType – 参数类型
　　	example – 举例说明

@ApiImplicitParams()  用于 controller 方法，包含多个 @ApiImplicitParam

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

四、例子

1、创建

UserManagerController.java

@RestController
@RequestMapping("user")
@Api(value = "UserManagerController", description = "用户管理")
public class UserManagerController {

@PostMapping
@ApiOperation(value = "添加用户")
public void addUser(User user) {
System.out.println(user.toString());
}

}

2、创建

User.java

@Data
public class User {
/**
* ApiModelProperty()用于方法，字段 表示对model属性的说明或者数据操作更改
* value–字段说明
* name–重写属性名字
* dataType–重写属性类型
* required–是否必填
* example–举例说明
* hidden–隐藏
*/
@ApiModelProperty(value="ID",name="id",example="1")
private Long id;

@ApiModelProperty(value="用户名",name="username",example="zhangxin")
private String username;

@ApiModelProperty(value="密码",name="password",example="123456")
private String password;
}

在代码中

@Data

lombok

lombok 官网

lombok 基本使用