源代码请添加笔者微信获取
微信号:FBIHackerHarryHao
微信二维码:
目录
【Swagger2】
主要内容
学习目标
一、Swagger简介
1.前言
2.Open API 是什么
3.Swagger简介
二、Springfox
三、Swagger极致用法
五、Swagger配置
1.配置基本信息
2.设置扫描的包
3.自定义注解设置不需要生成接口文档的方法
3.1自定义注解
3.2添加规则
3.3添加NotIncludeSwagger注解
4设置范围
六、Swagger2常用注解
1.Api
2.ApiOperation
3.ApiParam
4.ApiModel
5.ApiModelProperty
6.ApiIgnore
7.ApiImplicitParam
【Swagger2】
主要内容
- Swagger2简介
- Springfox
- Swagger2极致用法
- Swagger-UI使用
- Swagger2配置
- Swagger2常用注解
学习目标
知识点 |
要求 |
Swagger2简介 |
掌握 |
Springfox简介 |
掌握 |
Swagger2极致用法 |
掌握 |
Swagger-UI使用 |
掌握 |
Swagger2配置 |
掌握 |
Swagger2常用注解 |
掌握 |
一、Swagger简介
1.前言
接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变成重中之重。接口文档固然重要,但是由于项目周期等原因后端人员经常出现无法及时更新,导致前端人员抱怨接口文档和实际情况不一致。
很多人员会抱怨别人写的接口文档不规范,不及时更新。但是当自己写的时候确实最烦去写接口文档。这种痛苦只有亲身经历才会牢记于心。
如果接口文档可以实时动态生成就不会出现上面问题。
Swagger可以完美的解决上面的问题。
2.Open API 是什么
Open API规范(OpenAPI Specification)以前叫做Swagger规范,是REST API的API描述格式。
Open API文件允许描述整个API,包括:
每个访问地址的类型。POST或GET。
每个操作的参数。包括输入输出参数。
认证方法。
连接信息,声明,使用团队和其他信息。
Open API规范可以使用YAML或JSON格式进行编写。这样更利于我们和机器进行阅读。
OpenAPI规范(OAS)为REST API定义了一个与语言无关的标准接口,允许人和计算机发现和理解服务的功能,而无需访问源代码,文档或通过网络流量检查。正确定义后,消费者可以使用最少量的实现逻辑来理解远程服务并与之交互。
然后,文档生成工具可以使用OpenAPI定义来显示API,使用各种编程语言生成服务器和客户端的代码生成工具,测试工具以及许多其他用例。
源码和说明参照:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#oasDocument |
3.Swagger简介
Swagger是一套围绕Open API规范构建的开源工具,可以帮助设计,构建,记录和使用REST API。
Swagger工具包括的组件:
Swagger Editor :基于浏览器编辑器,可以在里面编写Open API规范。类似Markdown具有实时预览描述文件的功能。
Swagger UI:将Open API规范呈现为交互式API文档。用可视化UI展示描述文件。
Swagger Codegen:将OpenAPI规范生成为服务器存根和客户端库。通过Swagger Codegen可以将描述文件生成html格式和cwiki形式的接口文档,同时也可以生成多种言语的客户端和服务端代码。
Swagger Inspector:和Swagger UI有点类似,但是可以返回更多信息,也会保存请求的实际参数数据。
Swagger Hub:集成了上面所有项目的各个功能,你可以以项目和版本为单位,将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作,需要注册账号,分免费版和收费版。
使用Swagger,就是把相关的信息存储在它定义的描述文件里面(yml或json格式),再通过维护这个描述文件可以去更新接口文档,以及生成各端代码
二、Springfox
使用Swagger时如果碰见版本更新或迭代时,只需要更改Swagger的描述文件即可。但是在频繁的更新项目版本时很多开发人员认为即使修改描述文件(yml或json)也是一定的工作负担,久而久之就直接修改代码,而不去修改描述文件了,这样基于描述文件生成接口文档也失去了意义。
Marty Pitt编写了一个基于Spring的组件swagger-springmvc。Spring-fox就是根据这个组件发展而来的全新项目。
Spring-fox是根据代码生成接口文档,所以正常的进行更新项目版本,修改代码即可,而不需要跟随修改描述文件。
Spring-fox利用自身AOP特性,把Swagger集成进来,底层还是Swagger。但是使用起来确方便很多。
所以在实际开发中,都是直接使用spring-fox。
附:官网地址
http://springfox.github.io/springfox/ |
附:官方源码
https://github.com/springfox/springfox |
三、Swagger极致用法
编写SpringBoot项目
编写SpringBoot项目,项目中controller中包含一个Handler,测试项目,保证程序可以正确运行。
创建项目
创建项目开始=============================================================
创建项目结束=============================================================
修改pom.xml
导入lombok依赖
<!-- https://mvnrepository.com/artifact/org.projectlombok/lombok --> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <version>1.18.24</version> <scope>provided</scope> </dependency>
导入Spring-fox依赖
在项目的pom.xml中导入Spring-fox依赖。目前最新版本为2.9.2,所以导入的依赖也是这个版本。其中springfox-swagger2是核心内容的封装。springfox-swagger-ui是对swagger-ui的封装。
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
创建实体类People
package com.bjsxt.swagger.entity; import lombok.AllArgsConstructor; import lombok.Data; import lombok.NoArgsConstructor; import lombok.experimental.Accessors; @Accessors(chain = true) @AllArgsConstructor @NoArgsConstructor @Data public class People { private Long id; private String name; private String address; }
创建controller层
@RestController @RequestMapping("/people") public class DemoController { @RequestMapping("/getPeople") public People getPeople(Long id,String name,String address){ People people = new People(); people.setId(id); people.setName(name); people.setAddress(address); return people; } }
添加注解
在SpringBoot的启动类中添加@EnableSwagger2注解。
添加此注解后表示对当前项目中全部控制器进行扫描。应用Swagger2
package com.bjsxt.swagger; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import springfox.documentation.swagger2.annotations.EnableSwagger2; @EnableSwagger2 @SpringBootApplication public class SwaggerApplication { public static void main(String[] args) { SpringApplication.run(SwaggerApplication.class, args); } }
访问swagger-ui
启动项目后在浏览器中输入http://ip:port/swagger-ui.html即可以访问到swagger-ui页面,在页面中可以可视化的进行操作项目中所有接口。
四、Swagger-UI使用
访问swagger-ui.html后可以在页面中看到所有需要生成接口文档的控制器名称。
每个控制器中间包含多所有控制器方法的各种访问方式。如果使用的是@RequestMapping进行映射,将显示下面的所有请求方式。如果使用@PostMapping将只有Post方式可以能访问,下面也就只显示Post的一个。
点击某个请求方式中try it out
会出现界面要求输入的值。输入完成后点击Execute按钮
下面会出现Request URL以及不同状态码响应回来的结果。
五、Swagger配置
可以在项目中创建SwaggerConfig,进行配置文档内容。
1.配置基本信息
Docket:摘要对象,通过对象配置描述文件的信息。
apiInfo:设置描述文件中info。参数类型ApiInfo
select():返回ApiSelectorBuilder对象,通过对象调用build()可以创建Docket对象
ApiInfoBuilder:ApiInfo构建器。
@Configuration public class SwaggerConfig { @Bean public Docket getDocket(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(swaggerDemoApiInfo()) .select() .build(); } private ApiInfo swaggerDemoApiInfo() { return new ApiInfoBuilder() .contact(new Contact("北京尚学堂","http://www.bjsxt.com","[email protected]")) //文档标题 .title("这里是Swagger的标题") //文档描述 .description("这里是Swagger的描述") //文档版本 .version("1.0.0") .build(); } }
显示效果如下:
2.设置扫描的包
可以通过apis()方法设置哪个包中内容被扫描
就没有basic-error-controller了
3.自定义注解设置不需要生成接口文档的方法
3.1自定义注解
注解名称随意。
@Target({ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) public @interface NotIncludeSwagger { }
3.2添加规则
通过public ApiSelectorBuilder apis(Predicate<RequestHandler> selector)可以设置生成规则。
public static <T> Predicate<T> not(Predicate<T> predicate) :表示不允许的条件。
withMethodAnnotation:表示此注解是方法级别注解。
先静态导入这两个包
import static com.google.common.base.Predicates.not; import static springfox.documentation.builders.RequestHandlerSelectors.withMethodAnnotation;
3.3添加NotIncludeSwagger注解
在不需要生成接口文档的方法上面添加@NotIncludeSwagger注解后,该方法将不会被Swagger进行生成在接口文档中。
@NotIncludeSwagger @RequestMapping("/getPeople2") public People getPeople2(Long id, String name, String address) { People people = new People(); people.setId(id).setName(name).setAddress(address); return people; }
4设置范围
通过public ApiSelectorBuilder paths(Predicate<String> selector)可以设置满足什么样规则的url被生成接口文档。可以使用正则表达式进行匹配。
下面例子中表示只有以/demo/开头的url才能被swagger生成接口文档。
如果希望全部扫描可以使用paths(PathSelectors.any())
先静态导入下面的包
import static springfox.documentation.builders.PathSelectors.regex;
@Bean public Docket getDocket(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(swaggerDemoApiInfo()) .select() .paths(allowPaths()) .apis(RequestHandlerSelectors.basePackage("com.bjsxt.swagger.controller")) .apis(not(withMethodAnnotation(NotIncludeSwagger.class))) .build(); } private Predicate<String> allowPaths() { return or(regex("/demo/.*")); }
六、Swagger2常用注解
1.Api
@Api是类上注解。控制整个类生成接口信息的内容。
tags:类的名称。可以有多个值,多个值表示多个副本。
description:描述,已过时。
在swagger-ui.html中显示效果。
2.ApiOperation
@ApiOperation写在方法上,对方法进行总体描述
- value:接口描述
- notes:提示信息
代码示例:
在swagger-ui中显示效果
3.ApiParam
@ApiParam写在方法参数前面。用于对参数进行描述或说明是否为必添项等说明。
name:参数名称
value:参数描述
required:是否是必须
swagger-ui显示效果如下:
4.ApiModel
@ApiModel是类上注解,主要应用Model,也就是说这个注解一般都是写在实体类上。
- value:名称
- description:描述
代码示例:
5.ApiModelProperty
@ApiModelProperty可以用在方法或属性上。用于当对象作为参数时定义这个字段的内容。
value:描述
name:重写属性名
required:是否是必须的
example:示例内容
hidden:是否隐藏。
代码示例:
swagger-ui.html效果展示
6.ApiIgnore
@ApiIgnore用于方法或类或参数上,表示这个方法或类被忽略。和之前讲解的自定义注解@NotIncludeSwagger效果类似。只是这个注解是Swagger内置的注解,而@NotIncludeSwagger是我们自定义的注解。
![](/i/l/?n=23&i=blog/3094529/202302/3094529-20230210095829027-1565120348.png)
@ApiIgnore @RequestMapping("/getPeople3") public People getPeople3(Long id, String name, String address) { People people = new People(); people.setId(id).setName(name).setAddress(address); return people; }
swagger-ui.html效果展示
7.ApiImplicitParam
@ApiImplicitParam用在方法上,表示单独的请求参数,总体功能和@ApiParam类似。
name:属性名
value:描述
required:是否是必须的
paramType:属性类型
dataType:数据类型
代码示例:
@ApiOperation(value = "接口描述",notes = "接口提示信息") @ApiImplicitParam(name="address",value = "地址",required = true,paramType = "query",dataType = "string") @PostMapping("/getPeople4") public People getPeople4(Long id, @ApiParam(value = "姓名",required = true) String name, String address) { People people = new People(); people.setId(id); people.setName(name); people.setAddress(address); return people; }
swagger-ui.html效果展示
![](/i/l/?n=23&i=blog/3094529/202302/3094529-20230210095947110-1263386632.png)
如果希望在方法上配置多个参数时,使用@ApiImplicitParams进行配置。示例如下:
![](/i/l/?n=23&i=blog/3094529/202302/3094529-20230210095958459-1222381673.png)
@ApiOperation(value = "接口描述",notes = "接口提示信息") @PostMapping("/getPeople5") @ApiImplicitParams(value = { @ApiImplicitParam(name="id",value="编号",required = true), @ApiImplicitParam(name="name",value="姓名",required = true) }) public People getPeople5(Long id, @ApiParam(value = "姓名",required = true) String name, String address) { People people = new People(); people.setId(id); people.setName(name); people.setAddress(address); return people; }
swagger-ui.html效果展示
![](/i/l/?n=23&i=blog/3094529/202302/3094529-20230210100021614-597444004.png)
标签:源代码,people,Swagger2,swagger,文档,接口,注解,Swagger From: https://www.cnblogs.com/huanghaoheng/p/17107948.html