Spring Boot使開發RESTful服務變得非常容易 - 並且使用Swagger可以輕鬆地記錄RESTful服務。

構建後端API層引入了一個全新的領域，超越了僅僅實現端點的挑戰。 您現在有客戶端，現在將使用您的API。 您的客戶需要知道如何與您的API進行互動。 在基於SOAP的Web服務中，您有一個WSDL可以使用。 這為API開發人員提供了一個基於XML的合同，它定義了API。 但是，對於RESTFul Web服務，沒有WSDL。 因此，您的API文件變得更加重要。

API文件應該結構化，使其具有資訊性，簡潔性和易於閱讀。 但是最佳實踐，如何記錄你的API，它的結構，什麼包括和什麼不是是一個不同的主題，我不會在這裡覆蓋。

在本文中，我將介紹如何使用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規範，被稱為

我們將在我們的專案中使用Springfox。

為了引入它，我們需要在我們的Maven POM中有下​​面的依賴宣告。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
    <scope>compile</scope>
</dependency>
 

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.1</version>
    <scope>compile</scope>
</dependency>

Spring啟動RESTful應用程式

我們的應用程式實現了一組REST端點來管理產品。 我們有一個產品JPA實體和一個名為ProductRepository ，它擴充套件了CrudRepository ，以便針對記憶體中的H2資料庫執行產品的CRUD操作。

服務層由ProductService介面和ProductServiceImpl實現類組成。

Maven POM的應用程式是這樣的。

pom.xml ：

<?xml version="1.0" encoding="UTF-8"?>
<project
	xmlns="http://maven.apache.org/POM/4.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>guru.springframework</groupId>
	<artifactId>spring-boot-web</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<packaging>jar</packaging>
	<name>Spring Boot Web Application</name>
	<description>Spring Boot Web Application</description>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>1.4.2.RELEASE</version>
		<relativePath/>
		<!-- lookup parent from repository -->
	</parent>
	<properties>
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
		<java.version>1.8</java.version>
	</properties>
	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-data-rest</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-data-jpa</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-security</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-thymeleaf</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		<dependency>
			<groupId>com.jayway.jsonpath</groupId>
			<artifactId>json-path</artifactId>
			<scope>test</scope>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.6.1</version>
			<scope>compile</scope>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.6.1</version>
			<scope>compile</scope>
		</dependency>
		<!--WebJars-->
		<dependency>
			<groupId>com.h2database</groupId>
			<artifactId>h2</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>
	</dependencies>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>
</project>

應用程式的控制器ProductController定義REST API端點。 ProductController的程式碼是這樣的：

@RestController
@RequestMapping("/product")
public class ProductController {
    private ProductService productService;
    @Autowired
    public void setProductService(ProductService productService) {
        this.productService = productService;
    }
    @RequestMapping(value = "/list", method= RequestMethod.GET)
    public Iterable list(Model model){
        Iterable productList = productService.listAllProducts();
        return productList;
    }
    @RequestMapping(value = "/show/{id}", method= RequestMethod.GET)
    public Product showProduct(@PathVariable Integer id, Model model){
       Product product = productService.getProductById(id);
        return product;
    }
    @RequestMapping(value = "/add", method = RequestMethod.POST)
    public ResponseEntity saveProduct(@RequestBody Product product){
        productService.saveProduct(product);
        return new ResponseEntity("Product saved successfully", HttpStatus.OK);
    }
    @RequestMapping(value = "/update/{id}", method = RequestMethod.PUT)
    public ResponseEntity updateProduct(@PathVariable Integer id, @RequestBody Product product){
        Product storedProduct = productService.getProductById(id);
        storedProduct.setDescription(product.getDescription());
        storedProduct.setImageUrl(product.getImageUrl());
        storedProduct.setPrice(product.getPrice());
        productService.saveProduct(storedProduct);
        return new ResponseEntity("Product updated successfully", HttpStatus.OK);
    }
    @RequestMapping(value="/delete/{id}", method = RequestMethod.DELETE)
    public ResponseEntity delete(@PathVariable Integer id){
        productService.deleteProduct(id);
        return new ResponseEntity("Product deleted successfully", HttpStatus.OK);
    }
}

在這個控制器中，Spring 4.0中引入的@RestController註釋將ProductController標記為REST API控制器。 在引擎蓋下， @RestController工作作為一個方便的註釋用@Controller和@ResponseBody註釋類。

@RequestMapping類級註釋將請求對映到/product到ProductController類。 方法級別@RequestMapping註釋將Web請求對映到控制器的處理程式方法。

在應用程式中配置Swagger 2

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()                 .apis(RequestHandlerSelectors.basePackage("guru.springframework.controllers"))
                .paths(regex("/product.*"))
                .build();
    }
}

在此配置類中， @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 ：

package guru.springframework.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import static springfox.documentation.builders.PathSelectors.regex;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("guru.springframework.controllers"))
                .paths(regex("/product.*"))
                .build()
                .apiInfo(metaData());
    }
    private ApiInfo metaData() {
        ApiInfo apiInfo = new ApiInfo(
                "Spring Boot REST API",
                "Spring Boot REST API for Online Store",
                "1.0",
                "Terms of service",
                new Contact("John Thompson", "https://springframework.guru/about/", "[email protected]"),
               "Apache License Version 2.0",
                "https://www.apache.org/licenses/LICENSE-2.0");
        return apiInfo;
    }
}

在SwaggerConfig類中，我們添加了一個metaData()方法，該方法返回和使用有關我們的API的資訊ApiInfo物件。 第23行用新資訊初始化Docket。

Swagger 2生成的文件現在看起來類似於：

Swagger 2 REST端點的註釋

我們可以使用ProductController類上的ProductController來描述我們的API。

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

對於每個操作端點，我們可以使用@ApiOperation註釋來描述端點及其響應型別，如下所示：

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

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

花了我一些時間的一個未記錄的事情與響應內容型別的價值有關。 Swagger 2生成*/* ，而我期待應用application/json響應內容型別。 只有在更新了@RequestMapping註釋（產生= "application/json" 之後 ， = "application/json"生成所需的值。 帶註釋的ProductController如下。

ProductController.java ：

package guru.springframework.controllers;
import guru.springframework.domain.Product;
import guru.springframework.services.ProductService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/product")
@Api(value="onlinestore", description="Operations pertaining to products in Online Store")
public class ProductController {
    private ProductService productService;
    @Autowired
    public void setProductService(ProductService productService) {
        this.productService = productService;
    }
    @ApiOperation(value = "View a list of available products",response = Iterable.class)
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Successfully retrieved list"),
            @ApiResponse(code = 401, message = "You are not authorized to view the resource"),
            @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
            @ApiResponse(code = 404, message = "The resource you were trying to reach is not found")
    }
    )
    @RequestMapping(value = "/list", method= RequestMethod.GET, produces = "application/json")
    public Iterable<Product> list(Model model){
        Iterable<Product> productList = productService.listAllProducts();
        return productList;
    }
    @ApiOperation(value = "Search a product with an ID",response = Product.class)
    @RequestMapping(value = "/show/{id}", method= RequestMethod.GET, produces = "application/json")
    public Product showProduct(@PathVariable Integer id, Model model){
       Product product = productService.getProductById(id);
        return product;
    }
    @ApiOperation(value = "Add a product")
    @RequestMapping(value = "/add", method = RequestMethod.POST, produces = "application/json")
    public ResponseEntity saveProduct(@RequestBody Product product){
        productService.saveProduct(product);
        return new ResponseEntity("Product saved successfully", HttpStatus.OK);
    }
    @ApiOperation(value = "Update a product")
    @RequestMapping(value = "/update/{id}", method = RequestMethod.PUT, produces = "application/json")
    public ResponseEntity updateProduct(@PathVariable Integer id, @RequestBody Product product){
        Product storedProduct = productService.getProductById(id);
        storedProduct.setDescription(product.getDescription());
        storedProduct.setImageUrl(product.getImageUrl());
        storedProduct.setPrice(product.getPrice());
        productService.saveProduct(storedProduct);
        return new ResponseEntity("Product updated successfully", HttpStatus.OK);
    }
    @ApiOperation(value = "Delete a product")
    @RequestMapping(value="/delete/{id}", method = RequestMethod.DELETE, produces = "application/json")
    public ResponseEntity delete(@PathVariable Integer id){
        productService.deleteProduct(id);
        return new ResponseEntity("Product deleted successfully", HttpStatus.OK);
    }
}

當前文件缺少一件事：產品JPA實體的文件。 我們將為我們的模型生成文件。

Swagger 2註釋模型

您可以使用@ApiModelProperty註釋來描述Product模型的屬性。 使用@ApiModelProperty ，您還可以根據需要記錄屬性。

我們的產品類的程式碼是這樣的。

Product.java ：

package guru.springframework.domain;
import io.swagger.annotations.ApiModelProperty;
import javax.persistence.*;
import java.math.BigDecimal;
@Entity
public class Product {
    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    @ApiModelProperty(notes = "The database generated product ID")
    private Integer id;
    @Version
    @ApiModelProperty(notes = "The auto-generated version of the product")
    private Integer version;
    @ApiModelProperty(notes = "The application-specific product ID")
    private String productId;
    @ApiModelProperty(notes = "The product description")
    private String description;
    @ApiModelProperty(notes = "The image URL of the product")
    private String imageUrl;
    @ApiModelProperty(notes = "The price of the product", required = true)
    private BigDecimal price;
    public String getDescription() {
        return description;
    }
    public void setDescription(String description) {
        this.description = description;
    }
    public Integer getVersion() {
        return version;
    }
    public void setVersion(Integer version) {
        this.version = version;
    }
    public Integer getId() {
        return id;
    }
    public void setId(Integer id) {
        this.id = id;
    }
    public String getProductId() {
        return productId;
    }
    public void setProductId(String productId) {
        this.productId = productId;
    }
    public String getImageUrl() {
        return imageUrl;
    }
    public void setImageUrl(String imageUrl) {
        this.imageUrl = imageUrl;
    }
    public BigDecimal getPrice() {
        return price;
    }
    public void setPrice(BigDecimal price) {
        this.price = price;
    }
}

總結

除了使用Swagger Core和Swagger UI的REST API文件和演示外，Swagger 2還有許多其他用途，超出了本文的範圍。 我最喜歡的一個是Swagger Editor，一個工具來設計新的API或編輯現有的API。 編輯器視覺化呈現您的Swagger定義，並提供實時錯誤反饋。 另一個是Swagger Codegen ，一個程式碼生成框架，用於構建來自Swagger定義的客戶端SDK，伺服器和文件。

Swagger 2還支援通過JSON和YAML檔案定義Swagger。 如果你想通過在JSON和YAML檔案中外部化它們來避免程式碼庫中特定於實現的程式碼，那麼你應該嘗試一些東西 - 這將在以後的文章中介紹。