文章目录
1.介绍
1.前后端分离面临的情况
在前后端分离时,不可能要后端把所有接口都开发好,然后要前端去开发,需要前后端一起来做。这时我们需要一个文档,会详细的把后端需要开发哪些接口,这些接口需要接收什么样的参数,返回什么样的数据,在什么情况下返回的数据格式是什么样子的。前后端都拿着文档去开发。
在实际开发中,会需要经常修改接口,需要能够把接口的最新情况展示出来。Swagger通过一个网站可以实时显示后端的接口,还可以很方便的测试后端接口。
2.Swagger3 之 HelloWorld
1.创建springboot工程
引入web依赖,手动添加swagger3依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
2.swagger文档地址
文档接口地址:http://localhost:8080/v3/api-docs
文档页面地址:http://localhost:8080/swagger-ui/index.html
3.swagger文档基本配置
@Configuration
public class SwaggerConfig {
@Bean
Docket docket(){
return new Docket(DocumentationType.OAS_30)
// 要生成文档的接口
.select()
// 包
.apis(RequestHandlerSelectors.basePackage("com.ll.controller"))
// 所有类都生成
.paths(PathSelectors.any())
.build()
// 关于swagger网站的配置
.apiInfo(
new ApiInfoBuilder()
// 描述
.description("vhr 项目接口文档")
// 联系人
.contact(new Contact("lingling","https://www.ll.com","222@qq.com"))
.version("v1.0")
.title("API测试文档")
.license("Apache 2.0")
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
.build()
);
}
4.Swagger 各种注解
1.controller类注解
@GetMapping("/user/{id}")
// swagger2.0 方法名称
// @ApiOperation(value = "查询用户",notes = "根据id查询用户")
// swagger3.0 方法名称
@Operation(summary = "查询用户",description = "根据id查询用户")
// 方法参数 path:放到地址栏里 query:以key-value的方式传过来 body:放到请求体里
@ApiImplicitParam(paramType = "path",name = "id",value = "用户id")
// 有多个方法参数的情况
// @ApiImplicitParams(
// @ApiImplicitParam(paramType = "path",name = "id",value = "用户id")
// )
// swagger3.0 跟ApiImplicitParam差不多 @Parameter(name = "user")
// 忽略该接口 @ApiIgnore
@ApiResponses({
@ApiResponse(responseCode = "200",description = "请求成功"),
@ApiResponse(responseCode = "500",description = "请求失败")
})
public String getUserById(@PathVariable Integer id){
return "user "+id;
}
@PostMapping("user")
public String addUser(@RequestBody User user){
return user.toString();
}
2.model类注解
@ApiModel(value = "用户实体类",description = "这个类定义了用户")
public class User {
@ApiModelProperty("用户id")
private int id;
@ApiModelProperty("用户名称")
private int name;
}