Spring Boot集成Springfox Swagger3和簡單應用

摘要：Springfox Swagger能夠動態生成 API 接口供先後端進行交互和在線調試接口，Spring Boot 框架是目前很是流行的微服務框架，因此，在Spring Boot 項目中集成Springfox很是有意義。介紹Spring Boot集成Springfox Swagger3及swagger的簡單應用。

§前言

  Swagger是什麼？官方說法：Swagger是一個規範和完整的框架，用於建立、描述、調試和可視化 RESTful 風格的 Web 服務。通俗地說，Swagger 是一個主要用來在線建立文檔的插件，主要用來高質量地動態生成 API 接口供先後端進行交互和在線調試接口，若是不生成的話就須要寫靜態文檔來交互，那樣不只速度慢並且不容易修改。發現了痛點就要尋找解決方案，故Swagger應運而生。

  Springfox Swagger是Spring 基於swagger規範，能夠將基於SpringMVC和Spring Boot項目的源碼自動生成JSON格式的描述文件。自己不是屬於Swagger官網提供的。Spring Boot 框架是目前很是流行的微服務框架，因此，在Spring Boot 項目中集成Springfox很是有意義，能夠保證及時更新API文檔，下降先後端溝通成本，提升系統迭代效率。

  本文所用軟件開發環境以下：

  ♦ java version 13.0.1
  ♦ IntelliJ IDEA 2019.3.2 (Ultimate Edition)
  ♦ Spring Boot 2.3.1.RELEASE

§Spring Boot 集成 Springfox Swagger3

  若想爲Spring Boot項目添加無需任何配置的springfox，需引入其maven依賴庫：

<!--集成 springfox swagger3 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

  爲了便於管理API文檔，建議編寫一個Swagger配置類，這裏的配置類以下：

import org.springframework.beans.factory.annotation.Value;
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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * Swagger 配置類
 *
 * @author Wiener
 * @date 2021/2/26
 */
@EnableOpenApi
@Configuration
public class SwaggerConfig {
    //讀取application.properties 文件設置的是否開啓swagger屬性，正式環境通常須要關閉
    @Value(value = "${swagger.enabled}")
    Boolean swaggerEnabled;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo())
                // 是否開啓swagger
                .enable(swaggerEnabled).select()
                // 過濾條件，掃描指定路徑下的文件
                .apis(RequestHandlerSelectors.basePackage("com.eg.wiener.controller"))
                                //只保留/user/*風格的路徑，你們能夠調試一下
//                .paths(PathSelectors.ant("/user/*"))
                // 指定路徑處理，PathSelectors.any()表明不過濾任何路徑
                .paths(PathSelectors.any())
                .build().pathMapping("/");
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot集成Springfox Swagger示例")
                .description("樓蘭胡楊")
                // 開發者信息
                .contact(new Contact("樓蘭胡楊", "https://www.cnblogs.com/east7/", "wienerXXX@163.com"))
                .version("1.0.0")
                .build();
    }
}

  註解@EnableOpenApi用於開啓Swagger的自動配置，若是沒加的話，天然而然也就看不到後面的swagger UI面板了。經過select()函數返回一個ApiSelectorBuilder實例，用來控制哪些接口暴露給Swagger UI面板；在 Docket 上添加篩選條件。Docket 類提供了 apis() 和 paths() 兩個方法來幫助咱們在不一樣級別上過濾接口：

• apis() ：經過指定掃描路徑的方式，讓 Swagger 只去某些路徑下面掃描文件。
• paths() ：經過篩選 API 的 url 進行過濾。

  在上面的Swagger 配置類SwaggerConfig中，咱們定義了 Docket 實例的 apis() 和 paths()，那麼，swagger接口文檔界面將只會展現包com.eg.wiener.controller中的API。關於PathSelectors.ant()的用法，各位同仁能夠調試一下，因爲時間有限，不曾驗證是否可用。

  另外一種解決方案就是使用@ApiIgnore註解屏蔽某些API。若是想在API文檔中屏蔽掉某個接口，那麼只須要在這個接口上加上@ApiIgnore 便可。

豐富文檔內容

  在完成了上述配置後，已經算是初步集成Springfox Swagger3，能夠啓動服務查看API文檔內容了。可是這樣的文檔主要針對請求自己，描述信息的主要來源是函數的命名，對用戶並不友好，咱們一般須要使用swagger註解增長一些說明文字來使得API文檔內容更加豐滿。Swagger中經常使用的註解及其說明：

@Api：用在類上，說明該類的做用。
@ApiOperation：爲API增長方法說明。
@ApiImplicitParams : 用在方法上包含一組參數說明。
@ApiImplicitParam：給方法入參增長說明。
@ApiResponses：用於表示一組響應
@ApiResponse：用在@ApiResponses中，通常用於表達一個錯誤的響應信息
    l   code：數字，例如400
    l   message：信息，例如"必填參數不可爲空"
    l   response：拋出異常的類   
@ApiModel：描述一個Model的信息（通常用在請求參數沒法使用@ApiImplicitParam註解進行描述的時候）
    l   @ApiModelProperty：描述一個model的屬性

案例分析

  修改API實體類User，添加swagger註解：

@Setter
@Getter
@ToString
@ApiModel("用戶實體")
public class User implements Serializable {

    private static final long serialVersionUID = -8842370047277749376L;
    @ApiModelProperty("用戶 id")
    private Long id;
    @ApiModelProperty("用戶姓名")
    private String userName;
    private Integer age;
    private String address;
    private String mobilePhone;
    private String remark;

    public User() {
    }
    public User(Long id, String userName, Integer age) {
        this.id = id;
        this.userName = userName;
        this.age = age;
    }
}

  在實體類使用註解@ApiModel和 @ApiModelProperty能夠添加屬性備註，這些備註信息將展現在swagger頁面的Schema中，效果以下：

  在 controller 包下新建 UserController.java 類，經過在控制器類上增長 @Api 註解，能夠給控制器添加標籤信息。經過在接口方法上增長 @ApiOperation 註解來添加對接口的描述。關於swagger註解的更多信息，這裏就再也不闡述，須要的話，請去問問度娘。

/**
 * @author Wiener
 */
@RestController
@RequestMapping("/user")
@Api(tags="用戶API")
public class UserController {

    private static Logger logger = LoggerFactory.getLogger(UserController.class);

    /**
     * 同時使用 @RequestBody 與 @RequestParam()
     * http://localhost:8087/wiener/user/addUser?token=IamToken
     * @param user
     * @param token
     * @return
     * @throws Exception
     */
    @PostMapping("/addUser")
    @ApiOperation(value="用戶新增")
    public User addUser(@RequestBody User user, @RequestParam("token") String token) throws Exception {
        user.setRemark(token);
        return user;
    }
    /**
     * 示例地址 http://localhost:8087/wiener/user/getUser?id=9996669
     * @return
     * @throws Exception
     */
    @GetMapping("/getUser")
    @ApiOperation(value="用戶查詢(ID)")
    @ApiImplicitParam(name="id",value="查詢ID",required=true)
    public User getUser(Long id) throws Exception {
        logger.info("--------------------");
        User user = new User();
        user.setId(id);
        user.setAddress("測試地址是 " + UUID.randomUUID().toString());
        logger.info("類信息： {}", user.getClass());
        return user;
    }
}

  這個時候已經算是進一步集成Springfox-Swagger3了，啓動項目後訪問http://IP:port/your-app-root/swagger-ui/index.html能夠看到咱們的swagger文檔界面，其中，IP表示服務器IP地址，port表示項目配置的端口號，your-app-root表示項目配置的根路徑。在個人項目中，其訪問路徑是http://127.0.0.1:8087/wiener/swagger-ui/index.html，在瀏覽器訪問此URL進入以下文檔界面：

使用 SwaggerUI訪問API

  找到用戶查詢API getUser並進入接口詳情頁面，能夠在詳情頁面右側看到** Try it out** 按鈕，單擊此按鈕便可進入接口調用界面，在id輸入框隨機輸入一個Long類型的數字，單擊執行便可請求getUser方法：

  從API返回值能夠得出結論：使用 Swagger UI 成功訪問了API，故集成集成Springfox Swagger3完畢。有底氣甩了Postman了，你認爲呢？

§小結

  Springfox既能夠減小建立文檔的工做量，同時接口文檔又能夠融合到代碼之中去，使維護API文檔和修改代碼同步進行，讓咱們在修改代碼邏輯的同時方便的修改文檔說明，這太酷了。另外，Swagger UI界面頁提供了強大的頁面測試功能來調試每一個RESTful API。歡迎點贊閱讀，一同窗習交流；如有疑問，請在文章下方留下你的神評妙論！

§Reference

• https://developer.ibm.com/zh/languages/spring/articles/j-using-swagger-in-a-spring-boot-project/