Swagger2-SpringBoot

Spring Boot使开发RESTful服务变得非常容易 - 并且使用Swagger可以轻松地记录RESTful服务。

构建后端API层引入了一个全新的领域，超越了仅仅实现端点的挑战。 您现在有客户端，现在将使用您的API。 您的客户需要知道如何与您的API进行互动。 在基于SOAP的Web服务中，您有一个WSDL可以使用。 这为API开发人员提供了一个基于XML的合同，它定义了API。 但是，对于RESTFul Web服务，没有WSDL。 因此，您的API文档变得更加重要。

API文档应该结构化，使其具有信息性，简洁性和易于阅读。 但是最佳实践，如何记录你的API，它的结构，什么包括和什么不是是一个不同的主题，我不会在这里覆盖。 有关文档的最佳实践，我建议由Andy Wikinson进行此演示。

在本文中，我将介绍如何使用Swagger 2为Spring Boot项目生成REST API文档。

Swagger 2在Spring启动

Swagger 2是一个开源项目，用于描述和记录RESTful API。 Swagger 2是语言无关的，可扩展到除HTTP之外的新技术和协议。 当前版本定义了一组HTML，JavaScript和CSS资源，以便从符合Swagger的API动态生成文档。 这些文件由Swagger UI项目捆绑，以在浏览器上显示API。 除了渲染文档，Swagger UI允许其他API开发人员或用户与API的资源交互，而没有任何实现逻辑到位。

Swagger 2规范，被称为OpenAPI规范 ，有几个实现。 目前，Springfox已经取代了Swagger-SpringMVC（Swagger 1.2及以上版本）是Spring Boot应用程序的常用选项。 Springfox支持Swagger 1.2和2.0。

我们将在我们的项目中使用Springfox。

为了引入它，我们需要在我们的Maven POM中有下​​面的依赖声明。

1. <dependency>
2. <groupId>io.springfox </groupId>
3. <artifactId>springfox-swagger2 </artifactId>
4. <version>2.6.1 </version>
5. <scope>compile </scope>
6. </dependency>

除了Sprinfox，我们还需要Swagger UI。   包含Swagger UI的代码是这样的。

1. <dependency>
2. <groupId>io.springfox </groupId>
3. <artifactId>springfox-swagger-ui </artifactId>
4. <version>2.6.1 </version>
5. <scope>compile </scope>
6. </dependency>

Spring启动RESTful应用程序

我们的应用程序实现了一组REST端点来管理产品。 我们有一个产品JPA实体和一个名为ProductRepository ，它扩展了CrudRepository ，以便针对内存中的H2数据库执行产品的CRUD操作。

服务层由ProductService接口和ProductServiceImpl实现类组成。

Maven POM的应用程序是这样的。

pom.xml ：

1. <?xml version="1.0" encoding="UTF-8"?>
2. <project
3. xmlns= "http://maven.apache.org/POM/4.0.0"
4. xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance"
5. xsi:schemaLocation= "http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
6. <modelVersion>4.0.0 </modelVersion>
7. <groupId>guru.springframework </groupId>
8. <artifactId>spring-boot-web </artifactId>
9. <version>0.0.1-SNAPSHOT </version>
10. <packaging>jar </packaging>
11. <name>Spring Boot Web Application </name>
12. <description>Spring Boot Web Application </description>
13. <parent>
14. <groupId>org.springframework.boot </groupId>
15. <artifactId>spring-boot-starter-parent </artifactId>
16. <version>1.4.2.RELEASE </version>
17. <relativePath/>
18. <!-- lookup parent from repository -->
19. </parent>
20. <properties>
21. <project.build.sourceEncoding>UTF-8 </project.build.sourceEncoding>
22. <java.version>1.8 </java.version>
23. </properties>
24. <dependencies>
25. <dependency>
26. <groupId>org.springframework.boot </groupId>
27. <artifactId>spring-boot-starter-data-rest </artifactId>
28. </dependency>
29. <dependency>
30. <groupId>org.springframework.boot </groupId>
31. <artifactId>spring-boot-starter-data-jpa </artifactId>
32. </dependency>
33. <dependency>
34. <groupId>org.springframework.boot </groupId>
35. <artifactId>spring-boot-starter-security </artifactId>
36. </dependency>
37. <dependency>
38. <groupId>org.springframework.boot </groupId>
39. <artifactId>spring-boot-starter-thymeleaf </artifactId>
40. </dependency>
41. <dependency>
42. <groupId>org.springframework.boot </groupId>
43. <artifactId>spring-boot-starter-web </artifactId>
44. </dependency>
45. <dependency>
46. <groupId>com.jayway.jsonpath </groupId>
47. <artifactId>json-path </artifactId>
48. <scope>test </scope>
49. </dependency>
50. <dependency>
51. <groupId>io.springfox </groupId>
52. <artifactId>springfox-swagger-ui </artifactId>
53. <version>2.6.1 </version>
54. <scope>compile </scope>
55. </dependency>
56. <dependency>
57. <groupId>io.springfox </groupId>
58. <artifactId>springfox-swagger2 </artifactId>
59. <version>2.6.1 </version>
60. <scope>compile </scope>
61. </dependency>
62. <!--WebJars-->
63. <dependency>
64. <groupId>com.h2database </groupId>
65. <artifactId>h2 </artifactId>
66. </dependency>
67. <dependency>
68. <groupId>org.springframework.boot </groupId>
69. <artifactId>spring-boot-starter-test </artifactId>
70. <scope>test </scope>
71. </dependency>
72. </dependencies>
73. <build>
74. <plugins>
75. <plugin>
76. <groupId>org.springframework.boot </groupId>
77. <artifactId>spring-boot-maven-plugin </artifactId>
78. </plugin>
79. </plugins>
80. </build>
81. </project>

应用程序的控制器ProductController定义REST API端点。 ProductController的代码是这样的：

1. @RestController
2. @RequestMapping( "/product")
3. public class ProductController {
4. private ProductService productService;
5. @Autowired
6. public void setProductService(ProductService productService) {
7. this.productService = productService;
8. }
9. @RequestMapping(value = "/list", method= RequestMethod.GET)
10. public Iterable list(Model model){
11. Iterable productList = productService.listAllProducts();
12. return productList;
13. }
14. @RequestMapping(value = "/show/{id}", method= RequestMethod.GET)
15. public Product showProduct(@PathVariable Integer id, Model model){
16. Product product = productService.getProductById(id);
17. return product;
18. }
19. @RequestMapping(value = "/add", method = RequestMethod.POST)
20. public ResponseEntity saveProduct(@RequestBody Product product){
21. productService.saveProduct(product);
22. return new ResponseEntity( "Product saved successfully", HttpStatus.OK);
23. }
24. @RequestMapping(value = "/update/{id}", method = RequestMethod.PUT)
25. public ResponseEntity updateProduct(@PathVariable Integer id, @RequestBody Product product){
26. Product storedProduct = productService.getProductById(id);
27. storedProduct.setDescription(product.getDescription());
28. storedProduct.setImageUrl(product.getImageUrl());
29. storedProduct.setPrice(product.getPrice());
30. productService.saveProduct(storedProduct);
31. return new ResponseEntity( "Product updated successfully", HttpStatus.OK);
32. }
33. @RequestMapping(value= "/delete/{id}", method = RequestMethod.DELETE)
34. public ResponseEntity delete(@PathVariable Integer id){
35. productService.deleteProduct(id);
36. return new ResponseEntity( "Product deleted successfully", HttpStatus.OK);
37. }
38. }

在这个控制器中，Spring 4.0中引入的@RestController注释将ProductController标记为REST API控制器。 在引擎盖下， @RestController工作作为一个方便的注释用@Controller和@ResponseBody注释类。

@RequestMapping类级注释将请求映射到/product到ProductController类。 方法级别@RequestMapping注释将Web请求映射到控制器的处理程序方法。

在应用程序中配置Swagger 2

对于我们的应用程序，我们将在Spring Boot配置中创建一个Docket bean，为应用程序配置Swagger 2。 Springfox Docket实例为主要的API配置提供了合理的默认值和方便的配置方法。 我们的Spring Boot配置类，SwaggerConfig就是这样。

1. @Configuration
2. @EnableSwagger2
3. public class SwaggerConfig {
4. @Bean
5. public Docket productApi() {
6. return new Docket(DocumentationType.SWAGGER_2)
7. .select() .apis(RequestHandlerSelectors.basePackage( "guru.springframework.controllers"))
8. .paths(regex( "/product.*"))
9. .build();
10. }
11. }

在此配置类中， @EnableSwagger2注释在类中启用Swagger支持。 在Docket bean实例上调用的select()方法返回一个ApiSelectorBuilder ，它提供了用于过滤使用String谓词记录的控制器和方法的apis()和paths()方法。

在代码中， RequestHandlerSelectors.basePackage谓词匹配guru.springframework.controllers基础包以过滤API。 传递给paths()的regex参数用作附加过滤器，以便仅对以/product开头的路径生成文档。

此时，您应该能够通过启动应用程序并将浏览器指向http：// localhost：8080 / v2 / api-docs来测试配置 。

显然，Swagger 2为我们的端点生成的上述JSON转储不是我们想要的。

我们想要的是一些很好的人类可读的结构化文档，这是Swagger UI接管的地方。

在将浏览器指向http：// localhost：8080 / swagger-ui.html时，您将看到由Swagger UI呈现的生成文档，如下所示：

如你所见，Swagger 2使用了合理的默认值来生成ProductController的ProductController 。

然后，Swagger UI包装一切，为我们提供一个直观的UI。 这一切都是自动完成的。 我们没有写任何代码或其他文档来支持Swagger。

自定义Swagger

到目前为止，我们一直在看Swagger文档，因为它开箱即用 - 但Swagger 2有一些伟大的自定义选项。

让我们开始通过在SwaggerConfig类中提供有关我们的API的信息来定制Swagger。

SwaggerConfig.java ：

1. package guru.springframework.config;
2. import org.springframework.context.annotation.Bean;
3. import org.springframework.context.annotation.Configuration;
4. import springfox.documentation.builders.RequestHandlerSelectors;
5. import springfox.documentation.service.ApiInfo;
6. import springfox.documentation.service.Contact;
7. import springfox.documentation.spi.DocumentationType;
8. import springfox.documentation.spring.web.plugins.Docket;
9. import springfox.documentation.swagger2.annotations.EnableSwagger2;
10. import static springfox.documentation.builders.PathSelectors.regex;
11. @Configuration
12. @EnableSwagger2
13. public class SwaggerConfig {
14. @Bean
15. public Docket productApi() {
16. return new Docket(DocumentationType.SWAGGER_2)
17. .select()
18. .apis(RequestHandlerSelectors.basePackage( "guru.springframework.controllers"))
19. .paths(regex( "/product.*"))
20. .build()
21. .apiInfo(metaData());
22. }
23. private ApiInfo metaData() {
24. ApiInfo apiInfo = new ApiInfo(
25. "Spring Boot REST API",
26. "Spring Boot REST API for Online Store",
27. "1.0",
28. "Terms of service",
29. new Contact( "John Thompson", "https://springframework.guru/about/", "john@springfrmework.guru"),
30. "Apache License Version 2.0",
31. "https://www.apache.org/licenses/LICENSE-2.0");
32. return apiInfo;
33. }
34. }

在SwaggerConfig类中，我们添加了一个metaData()方法，该方法返回和使用有关我们的API的信息ApiInfo对象。 第23行用新信息初始化Docket。

Swagger 2生成的文档现在看起来类似于：

Swagger 2 REST端点的注释

此时，如果单击产品控制器链接，Swagger UI将显示我们的操作端点的文档，如下所示：  

我们可以使用ProductController类上的ProductController来描述我们的API。

@RestController @RequestMapping("/product") @Api(value="onlinestore", description="Operations pertaining to products in Online Store") public class ProductController { 

Swagger UI生成的文档将反映描述，现在看起来像这样：

对于每个操作端点，我们可以使用@ApiOperation注释来描述端点及其响应类型，如下所示：

1. @ApiOperation(value = "View a list of available products", response = Iterable.class)
2. @RequestMapping(value = "/list", method= RequestMethod.GET,produces = "application/json")
3. public Iterable list(Model model){
4. Iterable productList = productService.listAllProducts();
5. return productList;
6. }

Swagger 2还允许覆盖HTTP方法的默认响应消息。   除了常规的HTTP 200 OK之外，您还可以使用@ApiResponse注释来记录其他响应，如下所示。

1. @ApiOperation(value = "View a list of available products", response = Iterable.class)
2. @ApiResponses(value = {
3. @ApiResponse(code = 200, message = "Successfully retrieved list"),
4. @ApiResponse(code = 401, message = "You are not authorized to view the resource"),
5. @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
6. @ApiResponse(code = 404, message = "The resource you were trying to reach is not found")
7. }
8. )
9. @RequestMapping(value = "/list", method= RequestMethod.GET, produces = "application/json")
10. public Iterable list(Model model){
11. Iterable productList = productService.listAllProducts();
12. return productList;
13. }

花了我一些时间的一个未记录的事情与响应内容类型的价值有关。 Swagger 2生成*/* ，而我期待应用application/json响应内容类型。 只有在更新了@RequestMapping注释（产生= "application/json" 之后 ， = "application/json"生成所需的值。 带注释的ProductController如下。

ProductController.java ：

1. package guru.springframework.controllers;
2. import guru.springframework.domain.Product;
3. import guru.springframework.services.ProductService;
4. import io.swagger.annotations.Api;
5. import io.swagger.annotations.ApiOperation;
6. import io.swagger.annotations.ApiResponse;
7. import io.swagger.annotations.ApiResponses;
8. import org.springframework.beans.factory.annotation.Autowired;
9. import org.springframework.http.HttpStatus;
10. import org.springframework.http.ResponseEntity;
11. import org.springframework.ui.Model;
12. import org.springframework.web.bind.annotation.*;
13. @RestController
14. @RequestMapping( "/product")
15. @Api(value= "onlinestore", description= "Operations pertaining to products in Online Store")
16. public class ProductController {
17. private ProductService productService;
18. @Autowired
19. public void setProductService(ProductService productService) {
20. this.productService = productService;
21. }
22. @ApiOperation(value = "View a list of available products",response = Iterable.class)
23. @ApiResponses(value = {
24. @ApiResponse(code = 200, message = "Successfully retrieved list"),
25. @ApiResponse(code = 401, message = "You are not authorized to view the resource"),
26. @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
27. @ApiResponse(code = 404, message = "The resource you were trying to reach is not found")
28. }
29. )
30. @RequestMapping(value = "/list", method= RequestMethod.GET, produces = "application/json")
31. public Iterable<Product> list(Model model){
32. Iterable<Product> productList = productService.listAllProducts();
33. return productList;
34. }
35. @ApiOperation(value = "Search a product with an ID",response = Product.class)
36. @RequestMapping(value = "/show/{id}", method= RequestMethod.GET, produces = "application/json")
37. public Product showProduct(@PathVariable Integer id, Model model){
38. Product product = productService.getProductById(id);
39. return product;
40. }
41. @ApiOperation(value = "Add a product")
42. @RequestMapping(value = "/add", method = RequestMethod.POST, produces = "application/json")
43. public ResponseEntity saveProduct(@RequestBody Product product){
44. productService.saveProduct(product);
45. return new ResponseEntity( "Product saved successfully", HttpStatus.OK);
46. }
47. @ApiOperation(value = "Update a product")
48. @RequestMapping(value = "/update/{id}", method = RequestMethod.PUT, produces = "application/json")
49. public ResponseEntity updateProduct(@PathVariable Integer id, @RequestBody Product product){
50. Product storedProduct = productService.getProductById(id);
51. storedProduct.setDescription(product.getDescription());
52. storedProduct.setImageUrl(product.getImageUrl());
53. storedProduct.setPrice(product.getPrice());
54. productService.saveProduct(storedProduct);
55. return new ResponseEntity( "Product updated successfully", HttpStatus.OK);
56. }
57. @ApiOperation(value = "Delete a product")
58. @RequestMapping(value= "/delete/{id}", method = RequestMethod.DELETE, produces = "application/json")
59. public ResponseEntity delete(@PathVariable Integer id){
60. productService.deleteProduct(id);
61. return new ResponseEntity( "Product deleted successfully", HttpStatus.OK);
62. }
63. }

浏览器上的操作端点的输出如下：

当前文档缺少一件事：产品JPA实体的文档。 我们将为我们的模型生成文档。

Swagger 2注释模型

您可以使用@ApiModelProperty注释来描述Product模型的属性。 使用@ApiModelProperty ，您还可以根据需要记录属性。

我们的产品类的代码是这样的。

Product.java ：

1. package guru.springframework.domain;
2. import io.swagger.annotations.ApiModelProperty;
3. import javax.persistence.*;
4. import java.math.BigDecimal;
5. @Entity
6. public class Product {
7. @Id
8. @GeneratedValue(strategy = GenerationType.AUTO)
9. @ApiModelProperty(notes = "The database generated product ID")
10. private Integer id;
11. @Version
12. @ApiModelProperty(notes = "The auto-generated version of the product")
13. private Integer version;
14. @ApiModelProperty(notes = "The application-specific product ID")
15. private String productId;
16. @ApiModelProperty(notes = "The product description")
17. private String description;
18. @ApiModelProperty(notes = "The image URL of the product")
19. private String imageUrl;
20. @ApiModelProperty(notes = "The price of the product", required = true)
21. private BigDecimal price;
22. public String getDescription() {
23. return description;
24. }
25. public void setDescription(String description) {
26. this.description = description;
27. }
28. public Integer getVersion() {
29. return version;
30. }
31. public void setVersion(Integer version) {
32. this.version = version;
33. }
34. public Integer getId() {
35. return id;
36. }
37. public void setId(Integer id) {
38. this.id = id;
39. }
40. public String getProductId() {
41. return productId;
42. }
43. public void setProductId(String productId) {
44. this.productId = productId;
45. }
46. public String getImageUrl() {
47. return imageUrl;
48. }
49. public void setImageUrl(String imageUrl) {
50. this.imageUrl = imageUrl;
51. }
52. public BigDecimal getPrice() {
53. return price;
54. }
55. public void setPrice(BigDecimal price) {
56. this.price = price;
57. }
58. }

Swagger 2为产品生成的文档是这样的：  

总结

除了使用Swagger Core和Swagger UI的REST API文档和演示外，Swagger 2还有许多其他用途，超出了本文的范围。 我最喜欢的一个是Swagger Editor，一个工具来设计新的API或编辑现有的API。 编辑器可视化呈现您的Swagger定义，并提供实时错误反馈。 另一个是Swagger Codegen ，一个代码生成框架，用于构建来自Swagger定义的客户端SDK，服务器和文档。

Swagger 2还支持通过JSON和YAML文件定义Swagger。 如果你想通过在JSON和YAML文件中外部化它们来避免代码库中特定于实现的代码，那么你应该尝试一些东西 - 这将在以后的文章中介绍。

此帖子的代码可以在这里下载。