zhangdy0 2019-04-23
Swagger 是一个简单、功能强大、非常流行的API 表达工具。基于Swagger 生成API,可以得到交互式文档、自动生成代码的SDK,以及API 的发现方式。
Swagger 允许用户在一个html5 web 页面中,对API 进行文档化和交互。
优点:
主要是 添加 swagger2 核心包 以及 swagger-ui界面包的依赖。
<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>
package com.rickie;
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.rickie.rest"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger构建RESTful API")
.description("")
.termsOfServiceUrl("")
.version("1.0")
.build();
}
}
如下是ProductController.java 的示例代码。
package com.rickie.rest;
import com.rickie.dto.Product;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import java.util.ArrayList;
import java.util.List;
@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);
}
}
@ApiOperation:
作用在方法上,表示一个http请求的操作 。
@ApiImplicitParam:
作用在方法上,表示单独的请求参数
参数:
1. name :参数名。
2. value : 参数的具体意义,作用。
3. required : 参数是否必填。
4. dataType :参数的数据类型。
5. paramType :查询参数类型,这里有几种形式:
@ApiImplicitParams:
用于方法,包含多个 @ApiImplicitParam。
@Api:
作用在类上,用来标注该类具体实现内容。标识这个类是swagger的资源 。
参数:
1. tags:允许您为操作设置多个标签的属性。
2. description:可描述该类的作用。
访问如下链接,可以看到第一张图片所示,显示所有的API 列表方法。
http://localhost:8080/swagger-ui.html
点击查看第一个方法/products,如下图所示,可以进行交互操作。
访问 http://localhost:8080/v2/api-docs 可以获取接口的JSON 描述文件,如下图所示。