Swagger

前言

現在很多項目都開始使用前后端分離的架構方式了，前后端分離帶來諸多好處的同時，也面臨了一些問題，比如前后端開發人員的協同問題。

之前一般是通過文檔的形式來定義接口，然后前后端開發人員根據接口去各自開發，但是測試的時候往往會發現有對應不上的情況！

前端添加一個字段，后端則可能修改一系列的方法，這種情況帶來了很大的麻煩，因此Swagger應運而生！

目錄

Swagger 概念

Swagger 使用場景

Swagger 配置-文檔信息

Swagger 配置-接口掃描/過濾

Swagger 配置-分組

Swagger 配置-API注解

 

使用 Swagger測試接口

Swagger 概念

Swagger主要應用於前后端分離項目的協同開發，通過簡單易用的配置，即可實現接口信息文檔的實時更新，使得開發更見高效和便捷！

Swagger 使用場景

從開發的角度，這是對於前后端分離而且前后端人員分離的情況的！

如果是前后端分離，但是前后端人員不分離、甚至就是一個人承包了前后端，那實屬沒必要了~~~

從項目周期的角度，Swagger 在開發和測試時使用，上線則需要關閉。

Swagger 配置

1. 添加依賴包：swagger2、swagger-ui

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->

<dependency>

  <groupId>io.springfox</groupId>

  <artifactId>springfox-swagger2</artifactId>

  <version>2.9.2</version>

</dependency>


<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->

<dependency>

  <groupId>io.springfox</groupId>

  <artifactId>springfox-swagger-ui</artifactId>

  <version>2.9.2</version>

</dependency>

 添加配置類，並開啟Swagger

package com.hwl.swgger01.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2 //並開啟Swagger
public class SwaggerConfig {
}

 完成上門兩步已經能使用Swagger了，非常簡單。

測試訪問 http://localhost:8080/swagger-ui.html

Swagger提供的界面有四個信息模塊，如上圖。

配置Swagger

實際開發中，我們一般不使用默認的配置，而是根據需要進行自定義自己的配置

Swagger的配置主要使用Docket這個實例提供的接口進行配置，從而實輕松現來接管默認配置。

 

 注入配置實例，並修改Swagger信息

package com.hwl.swgger01.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 java.util.ArrayList;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    //配置並注入swagger的Docket實例,接管默認的配置信息
    @Bean
    public Docket docket(){
        return new Docket( DocumentationType.SWAGGER_2 ) //參數 DocumentationType：SWAGGER_12/SWAGGER_2/SPRING_WEB
                .apiInfo( setApiInfo() );
    }

    //配置swagger的apiInfo,參考默認配置修改
    private ApiInfo setApiInfo(){

        Contact contact = new Contact( "工程師01","hello.com","[e-mail]" );//作者信息
        return new ApiInfo(
                "我的標題你做主",
                "swagger有點好用",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

} 

 運行查看修改結果：

 

 

自定義配置掃描接口

默認的配置是掃描出全部的接口的，例如springBoot默認的錯誤頁面的接口。有時候我們只希望掃描自己想要的接口，這種情況也是通過Docket對象來設置：

 //配置並注入swagger的Docket實例,接管默認的配置信息
    @Bean
    public Docket docket(){
        return new Docket( DocumentationType.SWAGGER_2 ) //參數 DocumentationType：SWAGGER_12/SWAGGER_2/SPRING_WEB
                .apiInfo( setApiInfo() )
                .select()
                .apis( RequestHandlerSelectors.basePackage("com.hwl.swgger01.controller") ) //配置掃描包
                .build();
    }

 

現在訪問只有我們指定包下面的接口了：

通過源碼發現這里的掃描策略有以下幾種

• any //掃描全部
• none //都不掃描
• withMethodAnnotation //掃描方法上的注
• withClassAnnotation //掃描類上的注解，參數,例子:RestController.calss就只會掃描這樣的類輸出api

以上我們是通過Docket對象的apis來設置掃描哪些包，但有時候我們需要的包下面有些類或接口又是不需要掃描的，這時候需要使用過濾：

.apis() //配置掃描哪些包
.paths（）//配置哪些需要過濾

 

Swagger的內置開關

Swagger是開發提供了方便，但是一旦產品上線，測需要去掉Swagger，除了直接的代碼摘除，其實Swagger提供了接口用來直接關閉：

 .enable( flag ) //flag為false則關閉Swagger

 

一般會根據項目的環境來判斷是否開啟，當環境為開發、測試環境時開啟：

 

 分組協同開發

.groupName("Group01")

 

各組來實現自己的Docket配置，從而實現各組的實際對外顯示情況：

　　//配置並注入swagger的Docket實例,接管默認的配置信息
    @Bean
    public Docket docket(){
        return new Docket( DocumentationType.SWAGGER_2 ) //參數 DocumentationType：SWAGGER_12/SWAGGER_2/SPRING_WEB
                .apiInfo( setApiInfo() )
                .groupName("Group01")
                .select()
                .apis( RequestHandlerSelectors.basePackage("com.hwl.swgger01.controller") ) //配置掃描哪些
                .build();
    }

    @Bean
    public Docket docket1(){
        return new Docket( DocumentationType.SWAGGER_2 )
                .apiInfo( setApiInfo() )
                .groupName("Group02");
    }

 

顯示如下：

 

實體類

在前后端分離協同開發中，除了需要溝通接口外，實體類也是很重要的。

使用Swagger后，只要掃描顯示的接口中，返回值帶有某個實體類，那么該實體類會自動被Swagger加入到module中顯示出來：

返回值：

 @RequestMapping("/getUser")
    public User hello(){
        return new User( "lihua","123456" );
    }

Swagger自動顯示相關的實體：

 

 此外，為了Swagger文檔的友好性，Swagger還提供了一些注解來對類、方法、字段等進行一個額外的注釋說明：

 

 如：

@ApiModel("用戶信息") 用來標注解釋實體類，訪問swagger時講看到注釋信息，提供了一定的友好度。

使用Swagger進行接口測試

swagger還直接提供了接口的測試功能，非常方便！