springboot+swagger接口文檔企業實踐(上)

一句話概括:對於產品開發,特別是前後端分離的開發模式,接口文檔是連接前後端的樞紐,本文對springboot+swagger在企業的實踐進行詳細描述。

1.引言

在軟件開發過程中,接口設計與接口文檔編寫是重要的一環,特別是在前後端分離的情況下,接口說明文檔是開發人員之間的連接點。接口文檔的編寫有很多方式,可以使用word,也可以使用編寫工具如小幺雞,這些基本屬於脫離代碼編寫的文檔,如果接口變化,需要額外修改文檔,增加工作量。如何提高寫接口文檔效率,在springboot開發中,結合swagger來提供接口文檔說明是一個很好的實踐,通過配置與註解,在編寫接口代碼過程中,同時也把接口文檔寫好,接口需要變更時,文檔也同時變更,具有工作量少,效率高,接口文檔直觀簡潔,可實時調用驗證等好處。本文基本springboot2+swagger2,結合在企業中的實踐,對接口文檔的編寫進行詳細說明,具體有如下內容:

  • swagger介紹及文檔生成說明
  • 使用springboot2+swagger2構建示例工程及配置描述
  • 使用註解添加文檔內容說明
  • 使用全局參數進行接口認證

如需看源碼,本文示例工程地址https://github.com/mianshenglee/my-example

2.swagger簡介

2.1 swagger 介紹

swagger官網地址https://swagger.io,從官網看出,它是一個規範 (OpenAPI Specification,OAS) 和完整的框架(如編輯器 Swagger Editor ,顯示組件 Swagger Editor ,代碼生成 Swagger Codegen ),用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。既然是規範,它定義了一系列與接口描述相關的規則,如文檔格式,文件結構,數據類型,請求方法等等,可參考官方規範說明https://swagger.io/specification/v2/,文件設計和編寫時一般是 YAML格式 (方便編寫),在傳輸時則會使用JSON(通用性強)。有了接口描述文件後,需要進行友好顯示,swagger提供了Swagger-UIhttps://swagger.io/tools/swagger-ui/。這個組件的作用就是把已經按規範寫好的yaml文件,通過接口文檔形式顯示。我們可以下載這個組件本地運行,它是一個靜態網頁,放到web容器(如apache,nginx)來運行。也可以使用官網的在線版本。如下:

Swagger-UI

至此,我們知道使用swagger進行接口文檔編寫步驟是:(1)編寫符合OAS的接口文件,(2)使用swagger-ui進行顯示。

2.2 springfox、swagger與springboot

從前面可知,編寫符合OAS的接口文件還是得手工編寫,swagger-ui顯示也不方便(需要人工離線部署或使用在線服務),現在java領域的web開發,基本都使用springmvc開發,有沒有更方便的方式來結合swagger進行接口文件編寫,而不需要 手工編寫,減少工作量?

牛人Marty Pitt編寫了一個基於Spring的組件swagger-springmvc:https://github.com/martypitt/swagger-springmvc-example,用於將swagger集成到springmvc中來。springfox則是從這個組件發展而來,它可以基於spring自動生成JSON的API文檔,現在通過https://github.com/martypitt/swagger-springmvc/地址會直接跳轉到springfox的github頁面,它的官網http://springfox.io。當前springfox已經是發佈了多個版本,本文使用的是springfox-swagger2的2.7.0的版本。對於swagger-ui,它也提供了springfox-swagger-ui,集成接口文檔顯示頁面。這樣,前面swagger的兩個步驟都可以自動完成。而現在我們開發java web應用基本都是使用springboot進行開發,使用它的自動配置與註解,更加方便開發。因此,基於swagger的規範,使用springfox的組件(swagger2和swagger-ui),結合springboot,可以讓接口文檔變得非常簡單,有效。總的來說,springfox是對swagger規範的在springmvc和springboot開發中的自動化實現。本文後續就是以這種方式進行具體的使用描述。

3. 使用springboot+swagger構建接口文檔

本章節將使用springboot2+swagger2構建示例工程,並對基本配置進行描述。

3.1 springboot示例工程搭建

(1) 創建項目:通過Spring Initializr 頁面生成一個空 Spring Boot 項目,添加web依賴。

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

(2)編寫示例接口:

  • 首先添加幾個通用包:vo,controller,service,model,exception,分別存放視圖層模型,控制層,服務層,數據模型層,異常對象等代碼。
  • 示例數據模型是User,對應有UserController,UserService,統一返回視圖模型ResponseResult,統一異常類UniRuntimeException。
  • 針對用戶管理,使用restful風格的接口,定義了對用戶的增刪改查,對應(POST,DELETE,PUT,GET請求),如下:
@RestController
@RequestMapping("/users")
public class UserController {
    @Autowired
    private UserService userService;
    
    /**
     * 查詢單個用戶
     */
    @GetMapping("/{userId}")
    public ResponseResult getUserById(@PathVariable long userId) {...}
    /**
     * 查詢多個用戶
     */
    @GetMapping()
    public ResponseResult getUsers() {...}
    /**
     * 添加多個用戶
     */
    @PostMapping()
    public ResponseResult addUsers(@RequestBody List<User> users) {...}
    /**
     * 添加單個用戶
     */
    @PostMapping("/user")
    public ResponseResult addUser(@RequestBody User user) {...}
    /**
     * 更新單個用戶
     */
    @PutMapping("/user")
    public ResponseResult updateUser(@RequestBody User user) {...} 
    /**
     * 刪除單個用戶
     */
    @DeleteMapping("/user")
    public ResponseResult deleteUser(long userId) {...}
}

注意:此處我們只關注接口的定義、參數和返回值,具體實體不列出(詳細可看源碼https://github.com/mianshenglee/my-example)。

至此,示例工程可以正常運行,具有以下接口:

  1. GET /users/{userId} 獲取單個用戶
  2. GET /users 獲取多個用戶
  3. POST /users 添加多個用戶
  4. POST /users/user 添加單個用戶
  5. PUT /users/user 更新單個用戶
  6. DELTE /users/user?userId=xx 刪除單個用戶

注意:接口的RequestMapping,如果不指定httpMethod,springfox會把這個方法的所有動作GET/POST/PUT/PATCH/DELETE的方法都列出來,因此,寫接口時,請指定實際的動作。

3.2 引入swagger2與基本配置

3.2.1 添加springfox-swagger依賴

爲了可以自動化生成符合swagger的接口描述文件,需要添加springfox的依賴,如下:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>

3.2.2 配置swagger

添加config包用於存放配置文件,添加以下Swagger2Config.java配置,如下:

@Configuration
@EnableSwagger2
public class Swagger2Config {
private ApiInfo apiInfo() {
    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("接口說明文檔")
                .description("API文檔描述")
                .version("0.0.1-SNAPSHOT")
                .build();
    }
}

此文件配置了Docket的Bean,包括api的基本信息,需要顯示的接口(apis),需要過濾的路徑(paths),這樣,就可以生成符合規範的接口文檔。

3.2.3 查看swagger自動生成的描述文檔

使用上面的配置集成swagger2後,啓動項目,輸入http://localhost:8080/swaggerdemo/v2/api-docs即可查看JSON格式的接口描述文檔。如下所示:

1573465257350

此文檔是符合OAS規範,但離可視化顯示和使用還差一步,就是如何把這些信息展示在界面上。

3.3 添加swagger-ui界面交互

爲了能可視化顯示接口文檔,springfox已提供界面顯示組件,添加以下依賴:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>

添加此依賴後,引入的springfox-swagger-ui.jar包中有swagger-ui.html頁面,使用地址http://localhost:8080/swaggerdemo/swagger-ui.html即可查看接口文檔頁面。在此文檔中,可以查看接口定義、輸入參數、返回值,也可以使用try it out調用接口進行調試。如下:

1573465932646

至此,通過前面示例,已經以最簡單的方式實現了使用swagger對接口文檔的自動生成和UI顯示,但相對於企業中實際開發使用接口文檔,還是有一定距離,包括:

  • 不能根據環境選擇顯示文檔(可能開發環境需要顯示,正式環境不需要)
  • 接口沒有功能說明和詳細描述
  • 輸入參數詳細說明和示例說明
  • 返回值的詳細說明和示例說明
  • 所有controller接口都返回了,沒有按需過濾需要的接口
  • 所有接口都可以調試,存在權限認證問題

針對這些問題,在企業實踐中,需要進行處理。

4. 【企業實踐】配置參數化與包過濾

4.1 配置參數化

一份接口文檔,一般都會有關於此文檔的基本信息,包括文檔標題、描述、接口版本、聯繫人等信息,swagger已提供了對應的配置項,如上面的示例中的apiInfo(),把基本信息寫在代碼中進行配置,這樣對修改不友好,因此,最好是把這些配置參數化,形成swagger的獨立配置文件,避免修改基本信息導致代碼的改動。

4.1.1 添加基本信息配置文件

resources/config目錄下,添加swagger.properties文件,把配置信息放到此文件中。

swagger.basePackage =me.mason.helloswagger.demo.controller
swagger.title = 應用API說明文檔
swagger.description = API文檔描述
swagger.version = 0.0.1-SNAPSHOT
swagger.enable = true
swagger.contactName = mason
swagger.contactEmail =
swagger.contactUrl =
swagger.license =
swagger.licenseUrl =

對應的,在config包下,添加SwaggerInfo對象,對應上述配置文件:

@Component
@ConfigurationProperties(prefix = "swagger")
@PropertySource("classpath:/config/swagger.properties")
@Data
public class SwaggerInfo {
    private String basePackage;
    private String antPath;
    private String title = "HTTP API";
    private String description = "Swagger 自動生成接口文檔";
    private String version ;
    private Boolean enable;
    private String contactName;
    private String contactEmail;
    private String contactUrl;
    private String license;
    private String licenseUrl;
}

官方建議對於這種自定義的配置,最好添加以下spring-boot-configuration-processor依賴,以生成配置元數據,否則在IDEA中,會有"spring boot configuration annotation processor not found in classpath"的警告:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <optional>true</optional>
</dependency>

4.1.2 集成配置swagger文檔

有了SwaggerInfo配置類,在集成swagger2的apiInfo()可以注入使用,以後需要改動時修改配置文件即可。

private ApiInfo apiInfo() {
    return new ApiInfoBuilder().title(swaggerInfo.getTitle())
        .description(swaggerInfo.getDescription())
        .version(swaggerInfo.getVersion())
        .licenseUrl(swaggerInfo.getLicenseUrl())
        .contact(
            new Contact(swaggerInfo.getContactName()
            ,swaggerInfo.getContactUrl()
            ,swaggerInfo.getContactEmail()))
        .build();
}

4.2 配置是否啓用文檔

對於不同環境,有可能需要啓用和關閉接口文檔,如在開發環境我們需要顯示接口文檔,但在正式線上環境,有時我們不希望對外公佈接口。此需求可以使用enable配置即可,結合配置文件中有swagger.enable配置項(false關閉,true啓用)。如下:

.enable(swaggerInfo.getEnable())

4.3 包過濾

swagger組件會自動掃描有Controller註解和RequestMapping註解的接口,轉換爲接口描述。在開發過程中,我們不希望項目中所有的接口都顯示出來,而是想把特定的包下的接口顯示即可。使用方法apis(),結合配置文件,可達到此效果。配置文件中swagger.basePackage配置(多個包使用";"分隔)。添加以下過濾函數:

private List<Predicate<RequestHandler>> apisFilter() {
    List<Predicate<RequestHandler>> apis = new ArrayList<>();
    String basePackageStr = swaggerInfo.getBasePackage();
    //包過濾
    if (StrUtil.isNotEmpty(basePackageStr)) {
        //支持多個包
        String[] basePackages = basePackageStr.split(";");
        if (null != basePackages && basePackages.length > 0) {
            Predicate<RequestHandler> predicate = input -> {
                // 按basePackage過濾
                Class<?> declaringClass = input.declaringClass();
                String packageName = declaringClass.getPackage().getName();
                return Arrays.asList(basePackages).contains(packageName);
            };
            apis.add(predicate);
        }
    }
    return apis;
}

上述功能是通過掃描到的接口與配置的包比較,在配置的包下則返回,否則過濾掉。然後在配置Docket時,添加此過濾。

builder = builder.apis(Predicates.or(apisFilter()));

此處使用Predicates.or,表示對返回的進行or操作,true的即顯示。

5.【企業實踐】使用註解添加文檔內容

經過上面的配置化,我們已經可以靈活構建文檔了。但文檔的內容還不豐富,對接口的描述不詳細,springfox把對接口的描述都通過註解的方式來完成,主要包括以下幾種註解:

  1. 數據模型註解:@ApiModel,實體描述;@ApiModelProperty,實體屬性描述
  2. 接口註解:@ApiOperation,接口描述;@ApiIgnore,忽略此接口
  3. 控制器註解:@Api,控制器描述
  4. 輸入參數註解:@ApiImplicitParams,接口多個參數;@ApiImplicitParam,單個參數;@ApiParam,單個參數描述
  5. 響應數據註解:@ResponseHeader,響應值header;@ApiResponses,響應值集;@ApiResponse,單個響應值

下面我們對註解的使用進行說明,並用註解添加示例中的接口描述。

5.1 數據模型(model)註解說明

開發過程中,對於MVC模式的接口,使用M(Model)進行數據通信,因此,需要對此數據模型進行有效的描述。對應的註解有:

  • @ApiModel:實體描述
  • @ApiModelProperty:實體屬性描述。

下表爲@ApiModelProperty的使用說明:

註解屬性 類型 描述
value String 字段說明。
name String 重寫字段名稱。
dataType Stirng 重寫字段類型。
required boolean 是否必填。
example Stirng 舉例說明。
hidden boolean 是否在文檔中隱藏該字段。
allowEmptyValue boolean 是否允許爲空。
allowableValues String 該字段允許的值。

本示例中,即User類,使用如下註解進行描述:

@ApiModel
public class User {
    @ApiModelProperty(value="id",required = true,example = "1")
    private long id;
    @ApiModelProperty(value="姓名",required = true,example = "張三")
    private String name;
    @ApiModelProperty(value="年齡",example = "10")
    private int age;
    @ApiModelProperty(value="密碼",required = true,hidden = true)
    private String password;
}

這樣,在接口文檔中,使用User作爲輸入參數時,可以看到這個模型的描述,如下:

1573550660883

5.2 控制器及接口註解說明

springfox 在自動化生成文檔時,如果不使用註解進行描述,控制器和接口基本是把代碼的類名,方法名,接口映射作爲顯示的內容。對於控制器和具體某個接口的描述,分別有:

  • @ApiIgnore: Swagger 文檔不會顯示擁有該註解的接口

  • @Api: 對控制器的描述

註解屬性 類型 描述
tags String[] 控制器標籤。
description String 控制器描述(該字段被申明爲過期)。
  • @ApiOperation: 對接口的描述。
註解屬性 類型 描述
value String 接口說明。
notes String 接口發佈說明。
tags Stirng[] 標籤。
response Class<?> 接口返回類型。
httpMethod String 接口請求方式。

在本示例中,在UserController中進行相應描述,如下:

@Api(tags = "用戶管理接口", description = "User Controller")
public class UserController {
    @ApiOperation(value = "根據ID獲取單個用戶信息", notes = "根據ID返回用戶對象")
    ...//省略
 @ApiOperation(value = "添加多個用戶", notes = "使用JSON以數組形式添加多個用戶")
    ...//其它
}

使用這些註解後,顯示的文檔如下:

1573551666969

5.3 接口輸入參數註解說明

5.3.1 SpringMVC的控制器參數使用

在介紹Swagger的接口輸入參數註解說明前,有必要對SpringMVC的接口參數有一個清晰的瞭解。我們知道SpringMVC是通過@RequestMapping把方法與請求URL對應起來,而調用接口方法時需要把參數傳給控制器。一般來說,SpringMVC的參數傳遞包括以下幾種:

  • 無註解參數
  • @RequestParam註解參數
  • 數組參數
  • JSON對象參數
  • REST風格參數

爲方便解釋,在本示例中,提供了ParamDemoController文件,裏面對應給出了各種參數的示例,讀者可參考查看,下面對這幾種參數進行描述。

(1)無註解參數

無註解下獲取參數,要求參數名稱與HTTP請求參數名稱一致,參數可以爲空。如下接口:

@GetMapping("/no/annotation")
public Map<String,Object> noAnnotation(Integer intVal, Long longVal, String str){}

調用時,可使用http://localhost:8080/no/annotation?inVal=10&longVal=100,參數str可爲空。

(2)@RequestParam註解參數

使用註解RequestParam獲取參數,可以指定HTTP參數和方法參數名的映射,而且不能爲空(但可通過required設置false來允許爲空)。如下接口:

@GetMapping("/annotation")
public Map<String,Object> annotation(@RequestParam("int_val") Integer intVal,@RequestParam("long_val") Long longVal,@RequestParam(value="str_val", required = false) String str){}

調用方法跟上面無註解的一樣。但如果沒有設置required=false,則必須傳入str參數。

(3)數組參數

使用數組做爲參數,調用接口時,數組元素使用逗號(,)分隔。如下接口:

@GetMapping("/array")
public Map<String,Object> requestArray(int[]intArr,long[]longArr,String[] strArr){}

調用此接口,可使用http://localhost:8080/array?intArr=10,11,12&longArr=100,101,102&strArr=a,b,c

(4)JSON對象參數

當傳輸的數據相對複雜,或者與定義的模型相關,則需要把參數組裝成JSON進行傳遞,當前端調用接口時使用JSON請求體,SpringMVC可通過@RequestBody註解,實現JSON參數的映射,並進行合適的對象轉換。如下:

@PostMapping("/add/user")
public User addUser(@RequestBody User user){}

調用接口時,使用JSON傳遞參數,通過RequestBody註解得到JSON參數,映射轉換爲User對象。如果是數組(List)對象,同樣支持。

(5)REST風格參數

對於REST風格的URL,參數是寫在URL中,如users/1,其中1是用戶ID參數。對於此類參數,SpringMVC使用@PathVariable進行實現,其中使用{}作爲佔位符。如下:

@GetMapping("/users/{id}")
public User getUser(@PathVariable("id") Long id){}

5.3.2 swagger輸入參數註解說明

對於上面提到的的SpringMVC參數,springfox已經做了自動處理,在swagger-ui文檔中顯示時,也會根據參數類型進行顯示。在swagger中,參數類型分爲:

  • path:以地址的形式提交數據,根據 id 查詢用戶的接口就是這種形式傳參
  • query:Query string 的方式傳參,對應無註解和@RequestParam註解參數
  • header:請求頭(header)中的參數
  • form:以 Form 表單的形式提交,如上傳文件,屬於此類
  • body:以JSON方式傳參

在描述輸入參數時,swagger在以下註解:

  • @ApiImplicitParams: 描述接口的參數集。
  • @ApiImplicitParam: 描述接口單個參數,與 @ApiImplicitParams 組合使用。
  • @ApiParam:描述單個參數,可選

其中,@ApiParam與單個參數一起用,@ApiImplicitParam使用在接口描述中,兩者的屬性基本一致。@ApiImplicitParam的屬性如下所示:

註解屬性 描述
paramType 查詢參數類型,表示參數在哪裏,前面已提到,可取值: path,query,header,form,body。
dataType 參數的數據類型, 只作爲標誌說明,並沒有實際驗證,可按實際類型填寫,如String,User
name 參數名字
value 參數意義的描述
required 是否必填:true/false
allowMultiple 是否有多個,在使用JSON數組對象時使用
example 數據示例

以下是對使用JSON對象數組作爲參數的接口,如下:

@ApiOperation(value = "添加多個用戶", notes = "使用JSON以數組形式添加多個用戶")
@ApiImplicitParams({
    @ApiImplicitParam(name = "users", value = "用戶JSON數組", required = true, dataType = "User",allowMultiple = true)
})
@PostMapping()
public ResponseResult addUsers(@RequestBody List<User> users) {}

此示例中,使用@RequestBody註解,傳遞List<User>的JSON數組參數,因此,使用了allowMultiple屬性,dataType爲User,而它的paramTypebody。swagger文檔如下:

1573617046002

5.4 接口響應數據註解說明

對於使用了@RestController註解的控制器,SpringMVC會自動把返回的數據轉爲json數據。我們在開發過程中,一般都會把返回數據做統一封裝,返回狀態,信息,實際數據等等。如本示例中,以ResponseResult作爲統一返回結果,返回的數據使用泛型(若不使用泛型,後續swagger在顯示返回結果時對於Model的屬性則顯示不出來),如下:

@NoArgsConstructor
@AllArgsConstructor
@Data
public class ResponseResult<T> {
    @ApiModelProperty(value="返回狀態",example = "true")
    private boolean success;
    @ApiModelProperty(value="錯誤信息代碼")
    private String errCode;
    @ApiModelProperty(value="錯誤顯示信息")
    private String errShowMsg;
    @ApiModelProperty(value="錯誤信息")
    private String errMsg;
    @ApiModelProperty(value = "返回數據",notes = "若返回錯誤信息,此數據爲null或錯誤信息對象")
    private T resultData;
}

在接口返回值中,若不使用泛型指定具體Model,只返回ResponseResult,則只會顯示此對象中的屬性,而具體的resultData中的內容無法顯示,如下:

1573617582748

因此,對於統一返回,需要指定具體返回的模型,這樣,對於實際返回的模型就有對應的描述。如下:

@ApiOperation(value = "獲取所有用戶", notes = "返回全部用戶")
@GetMapping()
public ResponseResult<List<User>> getUsers() {}

1573619148261

對於響應消息,swagger提供了默認的401,403,404的響應消息,也可以自己針對接口進行指定,有以下註解可使用:

  • @ApiResponses:響應消息集
  • @ApiResponses:響應消息, 描述一個錯誤的響應信息 ,與@ApiResponses一起使用
  • @ResponseHeader:響應頭設置

6.【企業實踐】接口認證

對於對外發布的接口,一般都需要進行權限校驗,需要登錄的用戶纔可以調用,否則報權限不足。對於api的安全認證,一般有以下幾種模式(可參考swagger文檔:https://swagger.io/docs/specification/authentication/):

  • Basic 認證:使用Authorization請求頭,用戶名和密碼使用Base64編碼,如:Authorization: Basic ZGVtbzpwQDU1dzByZA==
  • Bearer 認證:使用Authorization請求頭,由服務端產生加密字符token,客戶端發送請求時把此token的請求頭髮到服務端作爲憑證,token格式是Authorization: Bearer <token>
  • API Keys認證:使用請求頭,參數或cookie,把只能客戶端和服務端知道的密鑰進行傳輸。
  • OAuth2: 一個開放標準,允許用戶授權第三方移動應用訪問他們存儲在另外的服務提供者上的信息,而不需要將用戶名和密碼提供給第三方移動應用或分享他們數據的所有內容 。

對於前後端分離的的springboot項目,現在很多采用jwt的認證方式(屬於Bearer認證),需要先獲取token,然後在調用接口時,添加類似Authorization: Bearer <token>的請求頭來對接口進行認證。針對這種方式,在Swagger中有以下三種方法來實現:

  1. 在接口參數描述中添加@ApiImplicitParam,其中參數類型是ParamType=header
  2. 添加全局接口參數
  3. 添加安全認證上下文

6.1 添加接口認證參數

針對需要認證的接口,直接使用@ApiImplicitParam,其中參數類型是ParamType=header即可,參數的描述前面已有介紹。如下:

@ApiImplicitParam(name = "Authorization", value = "token,格式: Bearer &lttoken&gt", required = false, dataType = "String",paramType = "header")

這種方式的缺點是,針對每一個接口,都需要添加這個參數描述,而描述都是一樣的,重複工作。

6.2 添加全局接口參數

swagger配置中,方法globalOperationParameters可以設置全局的參數。

//全局header參數
ParameterBuilder tokenPar = new ParameterBuilder();
List<Parameter> pars = new ArrayList<Parameter>();
tokenPar.name("Authorization").description("token令牌")
    .modelRef(new ModelRef("string"))
    .parameterType("header")
    .required(true).build();
pars.add(tokenPar.build());
docket.globalOperationParameters(pars);

這種方式缺點也明顯,由於設置了全局參數,則所有接口都需要此參數,若有某些接口不需要,則需要進行特殊處理。

6.3 添加安全認證上下文

設置認證模式,並使用正則式對需要認證的接口進行篩選,這樣swagger界面提供統一的認證界面。如下:

docket.securitySchemes(securitySchemes())
        .securityContexts(securityContexts());
...//省略
private List<ApiKey> securitySchemes() {
        return Lists.newArrayList(
                new ApiKey("Authorization", "Authorization", "header"));
    }
private List<SecurityContext> securityContexts() {
    return Lists.newArrayList(
        SecurityContext.builder()
        .securityReferences(defaultAuth())
        //正則式過濾,此處是所有非login開頭的接口都需要認證
        .forPaths(PathSelectors.regex("^(?!login).*$"))
        .build()
    );
}
List<SecurityReference> defaultAuth() {
    AuthorizationScope authorizationScope = new AuthorizationScope("global", "認證權限");
    return Lists.newArrayList(
        new SecurityReference("Authorization", new AuthorizationScope[]{authorizationScope}));
}

設置後,輸入登錄即可,效果如下:

1573630877692

7. 總結

本篇文章針對swagger的使用和企業實踐進行了詳細描述,主要介紹了swagger的原理,如何使用springboot與swagger結合創建接口文檔,對swagger進行參數化配置及包過濾,swagger註解的詳細使用,接口認證方法等,本文中使用的示例代碼已放在githubhttps://github.com/mianshenglee/my-example,有興趣的同學可以pull代碼,結合示例一起學習。

參考資料

往期文章

關注我的公衆號,獲取更多技術記錄:
mason

發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章