图2-17 Swagger生成文档的示例
(3)点击file-download yaml下载YAML文件。
(4)点击generate server下载服务端,点击generate client下载客户端,可以分别生成相应语言的SDK工程。
通过Spring Boot、Springfox、Swagger实现RESTful上一节介绍了通过Swagger Editor实现API设计(先写YAML文件,然后生成服务端和客户端),本节介绍另外一种直接写代码、通过注解自动生成相关文档的方法。
Spring Boot已经家喻户晓,而Springfox是什么呢?Marty Pitt曾经编写了一个基于Spring的组件swagger-springmvc,用于将Swagger集成到Spring MVC中,Springfox是从这个组件发展而来的。
下面我们通过一个简单的示例来说明一下。首先,新建一个项目,基于Maven构建,在pom中引入相应的JAR包,这里需要引入Spring Boot和Springfox的相关包。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
编写Swagger的配置类。
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.cloudnative.rest"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger构建RESTful API")
.description("")
.termsOfServiceUrl("")
.version("1.0")
.build();
}
}
实现dto类。
public class Product {
private int id;
private String name;
private int count;
private String desc;
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public int getCount() {
return count;
}
public void setCount(int count) {
this.count = count;
}
public String getDesc() {
return desc;
}
public void setDesc(String desc) {
this.desc = desc;
}
public int getId() {
return id;
}
public void setId(int id) {
this.id = id;
}
@Override
public String toString() {
return "Product{"
"id=" id
", name='" name '\''
", count=" count
", desc='" desc '\''
'}';
}
}
基于注解编写接口实现。
@RestController
@RequestMapping(value="/products") //通过这里配置使下面的映射都在/products下
public class ProductController {
private List<Product> productList;
//初始化
public ProductController(){
productList = new ArrayList<Product>();
for (int i = 0; i < 10; i ) {
Product product =new Product();
product.setId(i);
product.setCount(i 10);
product.setName("watch" i);
product.setDesc("watch desc" i);
productList.add(product);
}
}
@ApiOperation(value="获取产品列表", notes="获取产品列表")
@RequestMapping(value={""}, method= RequestMethod.GET)
public List<Product> getProductList() {
return productList;
}
@ApiOperation(value="获取产品详细信息", notes="根据url的id来获取产品详细信息")
@ApiImplicitParam(name = "id", value = "产品ID", required = true, dataType = "Integer",paramType="path")
@RequestMapping(value="/{id}", method=RequestMethod.GET)
public Product getProduct(@PathVariable Integer id) {
return productList.get(id);
}
}
基于Main方法启动。
@SpringBootApplication
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
访问http://localhost:8080/swagger-ui.html,自动生成的文档界面如图2-18所示。
图2-18 生成的文档界面
基于图2-18的界面进程测试,按“Try it out!”按钮执行,如图2-19所示。
图2-19 在生成的文档上进行测试
访问http://localhost:8080/v2/api-docs可以获取接口的JSON描述文件,如图2-20所示。可以直接到Swagger官网把JSON描述文件转换为YAML文件。
图2-20 转换为JSON的结构
HTTP协议的进化——HTTP/2据W3Techs统计,截至2017年11月,排在前1千万名的网站中有20.5%的支持HTTP/2。Chrome、Opera、Firefox、Internet Explorer 11、Safari、Amazon Silk和Edge浏览器都支持HTTP/2的标准化。大多数主流浏览器都在2015年底之前添加了HTTP/2支持。
HTTP/2对HTTP/1.x进行了大量简化,使得性能得到了大幅度提升。Akamai公司官网通过一个示例对比了HTTP/1.1和HTTP/2在性能上的差距——并发请求379张图片,HTTP/1.1需要14.70s,响应时间为3ms,而HTTP/2仅仅需要1.61s,响应时间为6ms,如图2-21所示。