Swagger介绍
-
基于 OpenAPI 规范（OpenAPI Specification，OAS）构建的开源接口文档自动生成工具，可以让开发人员快速设计、构建、记录以及使用 Rest API
-
Swagger 主要包含了以下三个部分：
- Swagger Editor：基于浏览器的编辑器，我们可以使用它编写我们 OpenAPI 规范。
- Swagger UI：它会将我们编写的 OpenAPI 规范呈现为交互式的 API 文档，后文我将使用浏览器来查看并且操作我们的 Rest API。
- Swagger Codegen：它可以通过为 OpenAPI（以前称为 Swagger）规范定义的任何 API 生成服务器存根和客户端 SDK 来简化构建过程。
使用介绍
1.SpringBoot添加pom文件依赖
-
io.springfox springfox-boot-starter3.0.0 2.application.properties 配置文件增加配置
-
#1024shop 是项目名 spring.application.name=1024shop # ===== 自定义swagger配置 ===== # swagger.enable=true swagger.application-name= ${spring.application.name} swagger.application-version=1.0 #swagger.application-description=1024shop电商平台管理后端接口文档 swagger.application-description=1024shop api info3.创建配置类
-
import io.swagger.annotations.ApiOperation; import lombok.Data; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.context.annotation.Bean; import org.springframework.stereotype.Component; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.oas.annotations.EnableOpenApi; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; @Component @EnableOpenApi @ConfigurationProperties("swagger") @Data public class SwaggerConfiguration{ private Boolean enable; private String applicationName; private String applicationVersion; private String applicationDescription; @Bean public Docket docket() { return new Docket(DocumentationType.OAS_30) .pathMapping("/") // 定义是否开启swagger，false为关闭，可以通过变量控制，线上关闭 .enable(enable) //配置api文档元信息 .apiInfo(apiInfo()) // 选择哪些接口作为swagger的doc发布 .select() //apis() 控制哪些接口暴露给swagger， // RequestHandlerSelectors.any() 所有都暴露 // RequestHandlerSelectors.basePackage("net.xdclass.*") 指定包位置 // withMethodAnnotation(ApiOperation.class)标记有这个注解 ApiOperation .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title(applicationName) .description(applicationDescription) //这里填接口文档的作者信息 .contact(new Contact("夕颜", "https://x.bfb6.cn", "3010147651@qq.com")) .version(applicationVersion) .build(); } }到这里基本配置就ok了
-
注意：如果你是springboot2.6.0以上，完成上方操作后运行会报错
-
解决方法 => application.properties 配置文件增加配置：spring.mvc.pathmatch.matching-strategy=ant_path_matcher
到这里就完全ok了
运行后浏览器访问:http://localhost:8081/swagger-ui/index.html#/
这个端口8081是springboot配置的项目端口
如果完成以上操作，并且接口文档链接可以访问，说明配置已经ok了，现在介绍怎么使用
在使用的类上方加 @Api注解，接口上方加@ApiOperation即可给对应的接口生成接口文档
各种情况代码如下，请看注释
import Util.JsonData;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;
@RestController
@RequestMapping("api/v1/user")
@Api(tags = "用户模块",value = "用户UserController")
public class UserController {
//@ApiOperation 接口配置，用在方法上，描述接口方法
//无参数get请求
@ApiOperation("分页用户列表")
@GetMapping("list")
public JsonData list(){
return JsonData.buildSuccess();
}
//@ApiParam 方法参数配置，用在入参上面，描述参数
//有参数post请求，参数加@ApiParam
@ApiOperation("用户登录")
@PostMapping("login")
public JsonData login(
@ApiParam(name = "phone", value = "手机号",example = "13888888888")
@RequestParam("phone") String phone,
@ApiParam(name = "pwd", value = "密码",example = "123456")
@RequestParam("pwd")String pwd){
return JsonData.buildSuccess();
}
//restful例子
@ApiIgnore // 忽略此接口，不生成对应文档
@ApiOperation("删除用户")
@DeleteMapping("/delete/{id}")
public JsonData deleteById(@PathVariable int id) {
return JsonData.buildSuccess();
}
}
点击运行即可把对应接口生成接口文档，接下来刷新接口文档地址
对应的接口就自动生成接口文档了
