通过Spring Boot、Springfox、Swagger实现RESTful
上一节介绍了通过Swagger Editor实现API设计（先写YAML文件，然后生成服务端和客户端），本节介绍另外一种直接写代码、通过注解自动生成相关文档的方法。
Spring Boot已经家喻户晓，而Springfox是什么呢？Marty Pitt曾经编写了一个基于Spring的组件swagger-springmvc，用于将Swagger集成到Spring MVC中，Springfox是从这个组件发展而来的。
下面我们通过一个简单的示例来说明一下。首先，新建一个项目，基于Maven构建，在pom中引入相应的JAR包，这里需要引入SpringBoot和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所示。
访问http://localhost:8080/v2/api-docs可以获取接口的JSON描述文件，如图2-20所示。可以直接到Swagger官网把JSON描述文件转换为YAML文件。
