Swagger 與 Spring Boot REST API 整合詳解

本文由碼農網 – Pansanday原創翻譯，轉載請看清文末的轉載要求，歡迎參與我們的付費投稿計劃！

在上一篇文章中，我談到了使用Spring Boot建立RESTFul服務的經驗。當建立一個REST API的時候，合適的文件是很重要的一部分。

Swagger是什麼

Swagger（Swagger 2）是描述和記錄REST API的一個規範。它指定了REST Web服務的格式，包括URL，資源，方法等。Swagger將從應用程式程式碼生成文件，並處理渲染部分。

在這篇文章中，我會將Swagger 2文件整合到基於Spring Boot的REST Web服務中。我將使用Springfox實現來生成swagger文件。如果你想知道是如何執行/構建Spring Boot專案的，請參考我上一篇文章。

Springfox提供了兩個依賴關係來生成API文件和Swagger UI。如果你不希望將Swagger UI整合到你的API中，則無需新增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>

@ EnableSwagger2註解啟用了Springfox Swagger在類中的支援。為了記錄這個服務，Springfox使用了一個Docket類。Docket有助於配置要記錄的服務，並通過名稱等進行分組。後臺是Springfox通過使用基於Spring配置的API語義，在執行時檢查應用程式。換句話說，你必須建立一個使用Spring的@Configuration註解的Spring Java Configuration類。

在我的例子中，我會生成一個基於我新增的RestController類的swagger文件。

import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class ApplicationConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.chandana.helloworld.controllers"))
                .paths(PathSelectors.any())
                .build();
    }
}

由於我新增了兩個控制器，因此將分別對每個控制器相關的API進行分組（標記）。

開箱即用，Springfox提供了5種斷言，它們分別是any，none，withClassAnnotation，withMethodAnnotation和basePackage【譯者注：參見springfox.documentation.builders. RequestHandlerSelectors類】

ApiInfo

Swagger提供了一些預設值，例如“API文件”，“通過聯絡人電子郵件建立”，“Apache 2.0”。當然你可以通過新增apiInfo（ApiInfo apiInfo）方法來更改這些預設值。ApiInfo類包含有關API的自定義資訊。

@Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.chandana.helloworld.controllers"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo getApiInfo() {
        Contact contact = new Contact("Chandana Napagoda", "http://blog.napagoda.com", "cnapagoda@gmail.com");
        return new ApiInfoBuilder()
                .title("Example Api Title")
                .description("Example Api Definition")
                .version("1.0.0")
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .contact(contact)
                .build();
    }

一旦新增了ApiInfo，生成的文件看起來就像這樣：

Controller和POJO層文件

@Api註解用於說明每個控制器類（有點像類註釋）。

@ApiOperation註解用於描述資源和方法。

@ApiResponse註解用於說明操作返回的其他響應值。例如：200 ok或202 accepted等

@ApiModelProperty註解用來描述POJO（Bean）類的屬性（屬性描述）。

新增上述註釋後，最終生成的swagger文件如下所示：

Spring RestController類：

package com.chandana.helloworld.controllers;

import com.chandana.helloworld.bean.Greeting;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
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;

@RestController
@RequestMapping("/api")
@Api(value = "user", description = "Rest API for user operations", tags = "User API")
public class HelloWorldController {

    @RequestMapping(value = "/hello/{name}", method = RequestMethod.GET, produces = "application/json")
    @ApiOperation(value = "Display greeting message to non-admin user", response = Greeting.class)
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "OK"),
            @ApiResponse(code = 404, message = "The resource not found")
    }
    )
    public Greeting message(@PathVariable String name) {
        Greeting msg = new Greeting(name, "Hello " + name);
        return msg;
    }
}

Greeting模型類：

package com.chandana.helloworld.bean;

import io.swagger.annotations.ApiModelProperty;

public class Greeting {

    @ApiModelProperty(notes = "Provided user name", required =true)
    private String player;

    @ApiModelProperty(notes = "The system generated greeting message" , readOnly =true)
    private String message;

    public Greeting(String player, String message) {
        this.player = player;
        this.message = message;
    }

    public String getPlayer() {
        return player;
    }

    public void setPlayer(String player) {
        this.player = player;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
}

AppConfig類：

package com.chandana.helloworld.config;

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class ApplicationConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.chandana.helloworld.controllers"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo getApiInfo() {
        Contact contact = new Contact("Chandana Napagoda", "http://blog.napagoda.com", "cnapagoda@gmail.com");
        return new ApiInfoBuilder()
                .title("Example Api Title")
                .description("Example Api Definition")
                .version("1.0.0")
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .contact(contact)
                .build();
    }
}

你也可以從我的GitHub repo 下載  Swagger Spring Boot Project 原始碼。

譯者注：

1. 如果你對Spring Boot不是很熟悉，建議先fork下原始碼，因為有些依賴文中沒有提到。
2. 啟動Spring Boot後，在瀏覽器中輸入：127.0.0.1:8080/swagger-ui.html即可檢視生成的文件資訊。

在生成的文件頁面中，可以輸入引數，點選“Try it out!”即可進行介面測試，有點類似於Postman的功能。