企业网站建设电话,安装百度到手机桌面,桂林生活网论坛论坛,WordPress点击logo返回首页Swagger
Swagger简介
Springboot整合swagger
Swagger 常用注解
一、Swagger简介
Swagger 是一系列 RESTful API 的工具#xff0c;通过 Swagger 可以获得项目的⼀种交互式文档#xff0c;客户端 SDK 的自动生成等功能。
Swagger 的目标是为 REST APIs 定义一个标…Swagger
Swagger简介
Springboot整合swagger
Swagger 常用注解
一、Swagger简介
Swagger 是一系列 RESTful API 的工具通过 Swagger 可以获得项目的⼀种交互式文档客户端 SDK 的自动生成等功能。
Swagger 的目标是为 REST APIs 定义一个标准的、与语⾔言无关的接口使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过 Swagger 定义消费者就能与远程的服务互动通过少量的实现逻辑。Swagger丝袜哥是世界上最流行的 API 表达工具。
二、Springboot整合swagger
使用 Spring Boot 集成 Swagger 的理念是使用用注解来标记出需要在 API 文档中展示的信息Swagger 会根据项目中标记的注解来生成对应的 API 文档。Swagger 被号称世界上最流行的 API 工具它提供了 API 管理的全套解决方案API 文档管理需要考虑的因素基本都包含这里将讲解最常用的定制内容。
1、添加swagger坐标
Spring Boot 集成 Swagger 3 很简单需要引入依赖并做基础配置即可。
dependencygroupIdio.springfox/groupIdartifactIdspringfox-boot-starter/artifactIdversion3.0.0/version
/dependency2、Swagger Helloword 实现
2.1、创建springboot项目
在启动类上加上EnableOpenApi 注解 启用swagger api文档功能
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.oas.annotations.EnableOpenApi;SpringBootApplication
EnableOpenApi //启动swagger api文档注解
public class SpringBootWithSwaggerApplication {public static void main(String[] args) {SpringApplication.run(SpringBootWithSwaggerApplication.class, args);}}
2.2、写一个接口
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;/*** author 阿水* create 2023-04-11 9:54*/
RestController()
public class SwaggerController {GetMapping (hello)public String hello(String params) {return hello swagger param为:params;}
} 2.3、访问地址
http://localhost:8080/swagger-ui/index.html三、常用的配置注解
Swagger 通过注解表明该接口会生成文档包括接口名、请求方法、参数、返回信息等
1、Api 注解和 ApiOperation 注解 Api 使用在类上表明是swagger资源API拥有两个属性:value、tags。 生成的api文档会根据tags分类直白的说就是这个controller中的所有接口生成的接口文档都会在tags这个list下tags如果有多个值会生成多个list每个list都显示所有接口 value的作用类似tags,但是不能有多个值 语法:Api(tags 用户操作)或Api(tags {用户操作,用户操作2})ApiOperation 使用于在方法上表示一个http请求的操作 语法:ApiOperation(value , notes , response )
属性说明value方法说明标题notes方法详细描述response方法返回值类型案例使用Api和ApiOperation生成api文档 import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;/*** author 阿水* create 2023-04-11 9:54*/
RestController()
Api(tags {操作用户})
public class SwaggerController {GetMapping (hello)ApiOperation(value swagger请求,notes 阿水的第一个swagger请求,response String.class)public String hello(String params) {return hello swagger param为:params;}
}2、ApiImplicitParams 注解和 ApiImplicitParam
ApiImplicitParams 注解和 ApiImplicitParam 用于对方法中的非对象参数(参数绑定到简单类型时使用。)进行说明
语法:
ApiImplicitParams(value {ApiImplicitParam(name, value , type , required true, paramType , defaultValue )
})属性说明name:形参名称value:形参的说明文字type:形参类型required:该参数是否必须 true|falseparamType: 用于描述参数是以何种方式传递到 Controller 的它的值常见有 path, query, body 和 header path 表示参数是『嵌在』路径中的它和 PathVariable 参数注解遥相呼应query 表示参数是以 query string 的形式传递到后台的无论是 get 请求携带在 url 中还是 post 请求携带在请求体中它和 RequestParam 参数注解遥相呼应header 表示参数是『藏在』请求头中传递到后台的它和 RequestHeader 参数注解遥相呼应的。form 不常用.defaultValue :参数默认值注意ApiImplicitParam 的 name 属性要和 RequestParam 或 PathVariable 的 value 遥相呼应。
案例使用ApiImplicitParams注解和 ApiImplicitParam 对方法参数进行说明
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;/*** author 阿水* create 2023-04-11 9:54*/
RestController()
Api(tags {操作用户})
public class SwaggerController {GetMapping (hello)ApiOperation(value swagger请求,notes 阿水的第一个swagger请求,response String.class)ApiImplicitParams(value {ApiImplicitParam(nameparam1,value 参数名1,type String,required true,paramType query,defaultValue 阿水所想的默认值1 ),ApiImplicitParam(nameparam2,value 参数名2,type String,required true,paramType query,defaultValue 阿水所想的默认值2 )})public String hello(String param1,String param2) {return hello swagger param1为:param1param2为param2;}
} 3、ApiModel注解和 ApiModelProperty ApiModel 用在实体类上表示对类进行说明用于实体类中的参数接收说明。 语法ApiModel(用户类)public class Users {}ApiModelProperty 用于对实体类中的属性进行说明 ApiModel(用户类)
Data
public class Users {ApiModelProperty(value 编码主键)private Integer id;ApiModelProperty(value 用户名)private String username;ApiModelProperty(value 密码)private String password;}4、ApiResponse 和 ApiResponses
ApiResponses 注解和 ApiResponse 标注在 Controller 的方法上用来描述 HTTP 请求的响应
/*** 添加用户** param user* return*/PostMapping(/add)ApiOperation(value 添加用户,notes 添加用户信息,response ResponseResult.class)ApiResponses({ ApiResponse(code 200, message 添加成功, response ResponseResult.class),ApiResponse(code 500, message 添加失败, response ResponseResult.class) })public ResponseResultVoid addUser(RequestBody User user) {//获得生成的加密盐user.setSalt(SaltUtils.getSalt());int n userService.addUser(user);if (n 0) {return new ResponseResultVoid(200, 添加成功);}return new ResponseResultVoid(500, 添加失败);}5、创建 SwaggerConfig 配置类
在 SwaggerConfig 中添加两个方法其中一个方法是为另一个方法作辅助的准备工作
api()方法使用 Bean在启动时初始化返回实例 DocketSwagger API 摘要对象这里需要注意的是 .apis(RequestHandlerSelectors.basePackage(xxx.yyy.zzz)) 指定需要扫描的包路路径只有此路径下的 Controller 类才会自动生成 Swagger API 文档。
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;/*** Swagger配置类*/
Configuration //项目启动时加载此类
public class SwaggerConfig {Beanpublic Docket api(){return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo()).select()// 此处自行修改为自己的 Controller 包路径。.apis(RequestHandlerSelectors.basePackage(com.lps.controller)).paths(PathSelectors.any()).build();}public ApiInfo apiInfo(){return new ApiInfoBuilder().title(阿水的项目接口文挡).description(阿水的 Project Swagger2 UserService Interface) //说明信息.termsOfServiceUrl(http://localhost:8080/swagger-ui/index.html) //文档生成的主页地址.version(1.0) //文档版本.build();}
}apiInfo()方法配置相对重要一些主要配置页面展示的基本信息包括标题、描述、版本、服务条款等查看 ApiInfo 类的源码还会发现支持 license 等更多的配置
四、springsecurity整合swagger
4.1配置放行的地址 http.authorizeRequests().antMatchers( /swagger-ui.html,/swagger-ui/*,/swagger-resources/**,/v2/api-docs,/v3/api-docs,/webjars/**).permitAll().anyRequest().authenticated();4.2替换UI
上面的整个过程已经完成了但是生成的接口文档的页面其实很多人不太喜欢觉得不太符合国人的使用习惯所有又有一些大神提供了其他的UI测试页面。这个页面的使用还是比较广泛的。
导入以下依赖、重启工程后访问地址http://localhost:8080/doc.html dependencygroupIdcom.github.xiaoymin/groupIdartifactIdswagger-bootstrap-ui/artifactIdversion1.9.6/version/dependency
