赞
踩
重点掌握:编写swagger的配置文件,理解每个配置的作用
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger让部署管理和使用功能强大的API变得非常简单。
简单来说,就是后端给前端提供的一个可以查看各种接口的方法、类型等。
作用:
简单的说:RESTful是一种架构的规范与约束、原则,符合这种规范的架构就是RESTful架构。
REST是英文representational state transfer(表现层状态转变)或者表述性状态转移,准确的说是Resource Representational State Transfer(资源表述性状态转移),就是资源在网络中以某种表现形式进行状态转化。Rest是web服务的一种架构风格;使用HTTP,URI,XML,JSON,HTML等广泛流行的标准和协议;轻量级,跨平台,跨语言的架构设计,它是一种设计风格,不是一种标准,是一种思想。
资源
“资源”是RESTful中最核心的概念之一。在RESTful概念中,互联网中的每一样信息都可以定义为资源,比如文本、图片、音频、视频等。而这些资源又都可以对应一个特定的URI(统一资源定位符),URI为每一个资源的地址或独一无二的识别符。
表现层
针对上面的“资源”,我们要进行相应的呈现,而且可以采用多种的呈现形式,而这些呈现形式就叫做“表现层”。
就拿文本为例,我们可以呈现为JSON格式、XML格式、HTML格式,甚至二进制格式等。这就是表现层所做的事情。
状态转化
资源通常放在服务器端,而客户端对服务器资源的增、删、改、查等操作,便涉及到资源状态的转化。这个过程便是“ 状态转化”。
我们以HTTP协议为例(RESTful不仅仅适用HTTP协议,只不过经常以HTTP协议为衬托),客户端可通过一些操作让服务器端的资源发生变化。而这整个过程,便是“表现层状态转化”。
在HTTP中,提供了四种常见的操作方式:GET、POST、PUT、DELETE。这四种操作方式分别对应四种基本操作:GET用来获取资源,POST用来新建资源(也可以用于更新资源),PUT用来更新资源,DELETE用来删除资源。
URI只是一种概念,怎样实现无所谓,只要它唯一标识一个资源就可以了。
URL是URI的一个子集,是Internet上描述信息资源的字符串,主要用在各种WWW客户程序和服务器程序上,是URI概念的一种实现方式。
URI和URL都定义了资源是什么,但URL还定义了该如何访问资源。URL是一种具体的URI,它是URI的一个子集,它不仅唯一标识资源,而且还提供了定位该资源的信息。URI 是一种语义上的抽象概念,可以是绝对的,也可以是相对的,而URL则必须提供足够的信息来定位,是绝对的。
只要能唯一标识资源的就是URI,在URI的基础上给出其资源的访问方式的就是URL
以上还理解不了,看下面这个按例,然后继续看上面的内容
1、新建SpringBoot项目,导入swagger依赖
IDEA建立一个SpringBoot Web工程
<!--swagger依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!--swagger ui-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
如果是3.0直接导入下面一个依赖即可
2、编写swagger的配置文件
当然了你可以配置一下 Swagger信息可参考如下
配置原理请参考此视频
@Configuration @EnableSwagger2 public class Swagger2Config { /** * 创建API应用 * apiInfo() 增加API相关信息 * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现, * 指定扫描的包路径来定义指定要建立API的目录。 * @return */ @Bean public Docket coreApiConfig(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(adminApiInfo()) .groupName("adminApi") .select() //只显示admin下面的路径 .paths(Predicates.and(PathSelectors.regex("/admin/.*"))) .build(); } private ApiInfo adminApiInfo(){ return new ApiInfoBuilder() .title("尚融宝后台管理系统--api文档") .description("尚融宝后台管理系统接口描述") .version("1.0") //作者信息 .contact(new Contact("李燕茹","http://baidu.com","728831102@qq.com")) .build(); } }
编写一个hello工程
启动项目 测试运行:http://localhost:8080/swagger-ui.html
为什么访问此路径可以出现这个页面,这个页面哪来的
Swagger配置Swagger部分信息及效果
Swaggeri配置扫描接口
配置是否启动Swagger
我只希望我的Swagger在生产环境中使用,在发布的时候不使用?
. 判断是不是生产环境flag=false
. 注入enable(flag)
配置API文档的分组
(groupName可以进行分组以区分后端开发者,如果有多个后端开发者,可以在Swagger2Config类里写多个Docket对象然后通过@Bean注入,不同的Docket对象代表不同的分组)
如何配置多个分组:多个Docket实例即可
为什么要分组:实际工作多人开发(系统协作开发),Bean可能来自很多类,最终都得被Spring托管,你写的Bean是管你的扫描的,别人写的Bean是管别人扫描的。
每个人(一个个Bean)扫描自己的包,对别人没影响
实体类信息的配置
这样是没有注释的,不太清楚每个字段含义,如何加上实体类的相关注释呢
给接口方法、参数加注释
更详细的说明请参见官方注解说明文档
Swagger常用注解1
swagger常用注解2
1、@ApiModel
使用场景:在实体类上使用,标记类时swagger的解析类
概述:提供有关swagger模型的其它信息,类将在操作中用作类型时自动内省
2、@ApiModelProperty
使用场景:使用在被 @ApiModel 注解的模型类的属性上。表示对model属性的说明或者数据操作更改
概述:添加和操作模型属性的数据
/**
* Student类 学生实体类
*/
@ApiModel(value = "Student",description = "用户实体类")
public class Student implements Serializable {
@ApiModelProperty(value = "学号")
private Integer id; //学号
@ApiModelProperty(value = "姓名")
private String name; //姓名
//日期的格式 年-月-日
@ApiModelProperty(value = "生日")
@DateTimeFormat(pattern = "yyyy-MM-dd")
private Date birthday; //生日
}
3、@ApiOperation
使用场景:使用在方法上,表示一个http请求的操作
概述:用来表示Controller类下的http请求方法
@ApiOperation("添加学生信息")
@PostMapping(value = "/student")
public void AddStudent(Student student) {
studentService.AddStudent(student);
}
4、@ApiParam
使用场景:在 Rest 接口上或 Rest 接口参数前边使用
概述:为 Rest 接口参数添加其它元数据(导入到 yapi 中不会被解析)
@ApiOperation("判断验证码是否正确")
@RequestMapping(value = "/UpdatePassword" , method = RequestMethod.POST)
public CommonResult updatePassword(
@ApiParam(value = "手机号码",required = true) @RequestParam String userPhone,
@ApiParam(value = "验证码",required = true) @RequestParam String authCode){
return userMemberService.updatePassword(userPhone,authCode);
}
@Api:修饰整个类,描述Controller的作用
@ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiParam:单个参数描述
@ApiModel:用对象来接收参数
@ApiProperty:用对象接收参数时,描述对象的一个字段
@ApiResponse:HTTP响应其中1个描述
@ApiResponses:HTTP响应整体描述
@ApiIgnore:使用该注解忽略这个API
@ApiError :发生错误返回的信息
@ApiImplicitParam:描述一个请求参数,可以配置参数的中文含义,还可以给参数设置默认值
@ApiImplicitParams:描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表
mplicitParam:描述一个请求参数,可以配置参数的中文含义,还可以给参数设置默认值
@ApiImplicitParams:描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表
knife4j官方文档
Spring Boot 基础教程:集成 Knife4j
swagger文档增强工具knife4j使用详解
先说一下引入这个依赖我们都能干嘛
Swagger 功能增强:接口搜索、离线文档下载、全局参数设置等功能…
①可以搜索接口名称快速定位接口(搜索功能)
②可以下载markdown、HTML、word 等格式文件(下载功能)
③。。。。。。自己去发现,更多详情戳我
①引入依赖 你可以去maven官网搜knife4j 我这里是springboot项目
注意:引入knife4j后会自动引入swagger相关依赖,所以无需再手动引入swagger相关依赖,否则会引起版本冲突,在使用knife4j的一些增强功能时会报错
<!-- knife4j接口文档 -->
<!-- <dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
-->
<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-boot-starter -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.2</version>
</dependency>
②添加SwaggerConfiguration作为Swagger2的配置类
这块就是我上面配置文件的基础上在加点注解啥的
关于这块配置类上的注解网上都不太一样,我也没此需求,也没验证,后期遇到我在更新。
需要的伙伴自行百度,能弄成效果即可
(解决SpringBoot使用knife4j无法引入@EnableSwagger2WebMvc:之前已经引入过了swagger2了,再引入Knife4j就会导致注解无法引入,把原来swagger2的东西注释掉后,这个注解就能正常引入了。)
(Knife4j 2.0.7默认引入swagger2.10.5,而swagger2.1版本开始引入了@EnableSwagger2WebMvc,废弃了@EnableSwagger2)
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Import; import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; /** * @类名: SwaggerConfiguration * @包名: com.blogs.web.blogsweb.config * @IDE的名称: IntelliJ IDEA * @当前项目的名称: blogsweb * @作者: YangMian * @时间: 2020/5/12 14:31 * @版本: 1.0.0 * <p>说明: </p> */ @Configuration @EnableSwagger2 @EnableKnife4j //@EnableSwagger2WebMvc 有用这个注解的 @Import(BeanValidatorPluginsConfiguration.class) public class SwaggerConfiguration { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) // 选择swagger2版本 .apiInfo(apiInfo()) //定义api文档汇总信息 .select() .apis(RequestHandlerSelectors .basePackage("com.blogsweb.web")) // 指定生成api文档的包 .paths(PathSelectors.any()) // 指定所有路径 .build() ; } /** * 构建文档api信息 * * @return */ private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("") // 文档标题 .contact(new Contact("", "", "")) //联系人信息 .description("") //描述 .version("1.0.1") //文档版本号 .termsOfServiceUrl("") //网站地址 .build(); } }
当然了你也可以先不做任何配置 输入localhost:8080/doc.html
进入如下页面
赞
踩
Copyright © 2003-2013 www.wpsshop.cn 版权所有,并保留所有权利。