Spring Boot整合swagger使用教程

目錄

• Swagger的介紹
  • 優點與缺點
• 新增swagger
  • 1.新增依賴包：
  • 2.配置Swagger:
  • 3.測試
• 場景：
  • 定義介面組
  • 定義介面
  • 定義介面請求引數
    • 場景一：請求引數是實體類。
    • 場景二：請求引數是非實體類。
  • 定義介面響應
    • 響應是實體類：
    • 響應是非實體類：
• Swagger UI增強
  • UI對比：
  • 使用
  • 優點
• 整合Spring Security注意
• 對於token的處理
• Swagger的安全管理

---

Swagger的介紹

?你可能嘗試過寫完一個介面後，自己去建立介面文件，或者修改介面後修改介面文件。多了之後，你肯定會發生一個操作，那就是忘記了修改文件或者建立文件（除非你們公司把介面文件和寫介面要求得很緊密?忘記寫文件就扣工資？，否則兩個分離的工作總是有可能遺漏的）。而swagger就是一個在你寫介面的時候自動幫你生成介面文件的東西，只要你遵循它的規範並寫一些介面的說明註解即可。

優點與缺點

?優點：

• 自動生成文件，只需要在介面中使用註解進行標註，就能生成對應的介面文件。
• 自動更新文件，由於是動態生成的，所以如果你修改了介面，文件也會自動對應修改（如果你也更新了註解的話）。這樣就不會傳送我修改了介面，卻忘記更新介面文件的情況。
• 支援線上除錯，swagger提供了線上呼叫介面的功能。

?缺點：

• 不能建立測試用例，所以他暫時不能幫你處理完所有的事情。他只能提供一個簡單的線上除錯，如果你想儲存你的測試用例，可以使用Postman或者YAPI這樣支援建立測試使用者的功能。
• 要遵循一些規範，它不是任意規範的。比如說，你可能會返回一個json資料，而這個資料可能是一個Map格式的，那麼我們此時不能標註這個Map格式的返回資料的每個欄位的說明，而如果它是一個實體類的話，我們可以通過標註類的屬性來給返回欄位加說明。也比如說，對於swagger，不推薦在使用GET方式提交資料的時候還使用Body，僅推薦使用query引數、header引數或者路徑引數，當然了這個限制只適用於線上除錯。
• 沒有介面文件更新管理，雖然一個介面更新之後，可能不會關心舊版的介面資訊，但你“可能”想看看舊版的介面資訊，例如有些灰度更新發布的時候可能還會關心舊版的介面。那麼此時只能由後端去看看有沒有註釋留下了，所以可以考慮介面文件大更新的時候註釋舊版的，然後寫下新版的。【當然這個問題可以通過匯出介面文件來對比。】
• 雖然現在Java的實體類中有不少模型，po,dto,vo等，模型的區分是為了遮蔽一些多餘引數，比如一個使用者登入的時候只需要username,password，但查許可權的時候需要連線上許可權表的資訊，而如果上述兩個操作都是使用了User這個實體的話，在文件中就會自動生成了多餘的資訊，這就要求了你基於模型來建立多個實體類，比如登入的時候一個LoginForm，需要使用者-許可權等資訊的時候才使用User類。（當然了，這個問題等你會swagger之後你就大概就會怎麼規避這個問題了。）

?上面的缺點好像寫的有點多，你可能會覺得swagger這個坑有點大。但其實主要是規範問題，而規範問題有時候又會提高你的程式碼規範性，這個就見仁見智了，你以前可能什麼介面的引數都使用一個類，而現在swagger要求你分開後，某種層次上提高了你的程式碼規範性。

?注：以下程式碼示例基於Spring Boot。完整程式碼可以參考：swagger-demo

---

新增swagger

?這裡先講新增swagger，也就是先整合進來，至於怎麼使用，下面的“場景”中再講解。

1.新增依賴包：

❗注意，這裡的前提是已經匯入了spring boot的web包。

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

2.配置Swagger:

要使用swagger，我們必須對swagger進行配置，我們需要建立一個swagger的配置類，比如可以命名為SwaggerConfig.java

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


@Configuration // 標明是配置類
@EnableSwagger2 //開啟swagger功能
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)  // DocumentationType.SWAGGER_2 固定的，代表swagger2
//                .groupName("分散式任務系統") // 如果配置多個文件的時候，那麼需要配置groupName來分組標識
                .apiInfo(apiInfo()) // 用於生成API資訊
                .select() // select()函式返回一個ApiSelectorBuilder例項,用來控制介面被swagger做成文件
                .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 用於指定掃描哪個包下的介面
                .paths(PathSelectors.any())// 選擇所有的API,如果你想只為部分API生成文件，可以配置這裡
                .build();
    }

    /**
     * 用於定義API主介面的資訊，比如可以宣告所有的API的總標題、描述、版本
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XX專案API") //  可以用來自定義API的主標題
                .description("XX專案SwaggerAPI管理") // 可以用來描述整體的API
                .termsOfServiceUrl("") // 用於定義服務的域名
                .version("1.0") // 可以用來定義版本。
                .build(); //
    }
}

3.測試

執行我們的Spring Boot專案，（我預設是8080埠，如果你不一樣，請注意修改後續的url），訪問http://localhost:8080/swagger-ui.html
然後你就可以看到一個如下的介面，由於我們暫時沒有配置介面資料，所以下面顯示No operations defined in spec!

?下面我們將介紹如何定義介面，以及在swagger UI介面中的內容。

---

場景：

定義介面組

介面有時候應該是分組的，而且大部分都是在一個controller中的，比如使用者管理相關的介面應該都在UserController中，那麼不同的業務的時候，應該定義/劃分不同的介面組。介面組可以使用@Api來劃分。
比如：

@Api(tags = "角色管理") //  tags：你可以當作是這個組的名字。
@RestController
public class RoleController {
}

和

@Api(tags = "使用者管理") //  tags：你可以當作是這個組的名字。
@RestController
public class UserController {
}

?你也可以理解成基於tags來分組，就好像一些文章裡面的標籤一樣，使用標籤來分類。
?如果這個Controller下（介面組）下面沒有介面，那麼在swagger ui中是不會顯示的，如果有的話就會這樣顯示：

定義介面

使用了@Api來標註一個Controller之後，如果下面有介面，那麼就會預設生成文件，但沒有我們自定義的說明：

@Api(tags = "使用者管理")
@RestController
public class UserController {
    // 注意，對於swagger，不要使用@RequestMapping，
    // 因為@RequestMapping支援任意請求方式，swagger會為這個介面生成7種請求方式的介面文件
    @GetMapping("/info") 
    public String info(String id){
        return "aaa";
    }
}

我們可以使用@ApiOperation來描述介面，比如：

    @ApiOperation(value = "使用者測試",notes = "使用者測試notes")
    @GetMapping("/test")
    public String test(String id){
        return "test";
    }

常用配置項：

• value：可以當作是介面的簡稱
• notes：介面的描述
• tags：可以額外定義介面組，比如這個介面外層已經有@Api(tags = "使用者管理")，將介面劃分到了“使用者管理”中，但你可以額外的使用tags，例如tags = "角色管理"讓角色管理中也有這個介面文件。

定義介面請求引數

上面使用了@ApiOperation來了描述介面，但其實還缺少介面請求引數的說明，下面我們分場景來講。
?注意一下，對於GET方式，swagger不推薦使用body方式來傳遞資料，也就是不希望在GET方式時使用json、form-data等方式來傳遞，這時候最好使用路徑引數或者url引數。(?雖然POSTMAN等是支援的)，所以如果介面傳遞的資料是json或者form-data方式的，還是使用POST方式好。

場景一：請求引數是實體類。

此時我們需要使用@ApiModel來標註實體類，然後在介面中定義入參為實體類即可：

• @ApiModel：用來標類
  • 常用配置項：
    • value：實體類簡稱
    • description：實體類說明
• @ApiModelProperty：用來描述類的欄位的意義。
  • 常用配置項：
    • value：欄位說明
    • example：設定請求示例（Example Value）的預設值，如果不配置，當欄位為string的時候，此時請求示例中預設值為"".
    • name：用新的欄位名來替代舊的欄位名。
    • allowableValues：限制值得範圍，例如{1,2,3}代表只能取這三個值；[1,5]代表取1到5的值；(1,5)代表1到5的值，不包括1和5；還可以使用infinity或-infinity來無限值，比如[1, infinity]代表最小值為1，最大值無窮大。
    • required：標記欄位是否必填，預設是false,
    • hidden：用來隱藏欄位，預設是false，如果要隱藏需要使用true，因為欄位預設都會顯示，就算沒有@ApiModelProperty。

// 先使用@ApiModel來標註類
@ApiModel(value="使用者登入表單物件",description="使用者登入表單物件")
public class LoginForm {
    // 使用ApiModelProperty來標註欄位屬性。
    @ApiModelProperty(value = "使用者名稱",required = true,example = "root")
    private String username;
    @ApiModelProperty(value = "密碼",required = true,example = "123456")
    private String password;

    // 此處省略入參賦值時需要的getter,setter,swagger也需要這個
}

定義成入參：

    @ApiOperation(value = "登入介面",notes = "登入介面的說明")
    @PostMapping("/login")
    public LoginForm login(@RequestBody LoginForm loginForm){
        return loginForm;
    }

效果：

場景二：請求引數是非實體類。

（再說一次：對於GET方式，swagger不推薦使用body方式來傳遞資料，所以雖然Spring MVC可以自動封裝引數，但對於GET請求還是不要使用form-data，json等方式傳遞引數，除非你使用Postman來測試介面，swagger線上測試是不支援這個操作的）
對於非實體類引數，可以使用@ApiImplicitParams和@ApiImplicitParam來宣告請求引數。
@ApiImplicitParams用在方法頭上，@ApiImplicitParam定義在@ApiImplicitParams裡面，一個@ApiImplicitParam對應一個引數。
@ApiImplicitParam常用配置項：

• name：用來定義引數的名字，也就是欄位的名字,可以與介面的入參名對應。如果不對應，也會生成，所以可以用來定義額外引數！
• value：用來描述引數
• required：用來標註引數是否必填
• paramType有path,query,body,form,header等方式，但對於對於非實體類引數的時候，常用的只有path,query,header；body和form是不常用的。body不適用於多個零散引數的情況，只適用於json物件等情況。【如果你的介面是form-data,x-www-form-urlencoded的時候可能不能使用swagger頁面API除錯，但可以在後面講到基於BootstrapUI的swagger增強中除錯，基於BootstrapUI的swagger支援指定form-data或x-www-form-urlencoded】

示例一：宣告入參是URL引數

    // 使用URL query引數
    @ApiOperation(value = "登入介面2",notes = "登入介面的說明2")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username",//引數名字
                    value = "使用者名稱",//引數的描述
                    required = true,//是否必須傳入
                    //paramType定義引數傳遞型別：有path,query,body,form,header
                    paramType = "query"
                    )
            ,
            @ApiImplicitParam(name = "password",//引數名字
                    value = "密碼",//引數的描述
                    required = true,//是否必須傳入
                    paramType = "query"
                    )
    })
    @PostMapping(value = "/login2")
    public LoginForm login2(String username,String password){
        System.out.println(username+":"+password);
        LoginForm loginForm = new LoginForm();
        loginForm.setUsername(username);
        loginForm.setPassword(password);
        return loginForm;
    }

示例二：宣告入參是URL路徑引數

    // 使用路徑引數
    @PostMapping("/login3/{id1}/{id2}")
    @ApiOperation(value = "登入介面3",notes = "登入介面的說明3")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id1",//引數名字
                    value = "使用者名稱",//引數的描述
                    required = true,//是否必須傳入
                    //paramType定義引數傳遞型別：有path,query,body,form,header
                    paramType = "path"
            )
            ,
            @ApiImplicitParam(name = "id2",//引數名字
                    value = "密碼",//引數的描述
                    required = true,//是否必須傳入
                    paramType = "path"
            )
    })
    public String login3(@PathVariable Integer id1,@PathVariable Integer id2){
        return id1+":"+id2;
    }

示例三：宣告入參是header引數

    // 用header傳遞引數
    @PostMapping("/login4")
    @ApiOperation(value = "登入介面4",notes = "登入介面的說明4")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username",//引數名字
                    value = "使用者名稱",//引數的描述
                    required = true,//是否必須傳入
                    //paramType定義引數傳遞型別：有path,query,body,form,header
                    paramType = "header"
            )
            ,
            @ApiImplicitParam(name = "password",//引數名字
                    value = "密碼",//引數的描述
                    required = true,//是否必須傳入
                    paramType = "header"
            )
    })
    public String login4( @RequestHeader String username,
                          @RequestHeader String password){
        return username+":"+password;
    }

示例四：宣告檔案上傳引數

    // 有檔案上傳時要用@ApiParam，用法基本與@ApiImplicitParam一樣，不過@ApiParam用在引數上
    // 或者你也可以不註解，swagger會自動生成說明
    @ApiOperation(value = "上傳檔案",notes = "上傳檔案")
    @PostMapping(value = "/upload")
    public String upload(@ApiParam(value = "圖片檔案", required = true)MultipartFile uploadFile){
        String originalFilename = uploadFile.getOriginalFilename();

        return originalFilename;
    }
    

    // 多個檔案上傳時，**swagger只能測試單檔案上傳**
    @ApiOperation(value = "上傳多個檔案",notes = "上傳多個檔案")
    @PostMapping(value = "/upload2",consumes = "multipart/*", headers = "content-type=multipart/form-data")
    public String upload2(@ApiParam(value = "圖片檔案", required = true,allowMultiple = true)MultipartFile[] uploadFile){
        StringBuffer sb = new StringBuffer();
        for (int i = 0; i < uploadFile.length; i++) {
            System.out.println(uploadFile[i].getOriginalFilename());
            sb.append(uploadFile[i].getOriginalFilename());
            sb.append(",");
        }
        return sb.toString();
    }



    // 既有檔案，又有引數
    @ApiOperation(value = "既有檔案，又有引數",notes = "既有檔案，又有引數")
    @PostMapping(value = "/upload3")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name",
                    value = "圖片新名字",
                    required = true
            )
    })
    public String upload3(@ApiParam(value = "圖片檔案", required = true)MultipartFile uploadFile,
                          String name){
        String originalFilename = uploadFile.getOriginalFilename();

        return originalFilename+":"+name;
    }

定義介面響應

定義介面響應，是方便檢視介面文件的人能夠知道介面返回的資料的意義。

響應是實體類：

前面在定義介面請求引數的時候有提到使用@ApiModel來標註類，如果介面返回了這個類，那麼這個類上的說明也會作為響應的說明：

    // 返回被@ApiModel標註的類物件
    @ApiOperation(value = "實體類響應",notes = "返回資料為實體類的介面")
    @PostMapping("/role1")
    public LoginForm role1(@RequestBody LoginForm loginForm){
        return loginForm;
    }

響應是非實體類：

swagger無法對非實體類的響應進行詳細說明，只能標註響應碼等資訊。是通過@ApiResponses和@ApiResponse來實現的。
@ApiResponses和@ApiResponse可以與@ApiModel一起使用。

    // 其他型別的,此時不能增加欄位註釋，所以其實swagger推薦使用實體類
    @ApiOperation(value = "非實體類",notes = "非實體類")
    @ApiResponses({
            @ApiResponse(code=200,message = "呼叫成功"),
            @ApiResponse(code=401,message = "無許可權" )
    }
    )
    @PostMapping("/role2")
    public String role2(){
        return " {\n" +
                " name:\"廣東\",\n" +
                "     citys:{\n" +
                "         city:[\"廣州\",\"深圳\",\"珠海\"]\n" +
                "     }\n" +
                " }";
    }

---

Swagger UI增強

你可能會覺得現在這個UI不是很好看，現在有一些第三方提供了一些Swagger UI增強，比較流行的是swagger-bootstrap-ui，我們這裡以swagger-bootstrap-ui為例。

UI對比：

使用

1.新增依賴包：

        <!--引入swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- 引入swagger-bootstrap-ui依賴包-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.8.7</version>
        </dependency>

2.在swagger配置類中增加註解@EnableSwaggerBootstrapUI:

@Configuration // 標明是配置類
@EnableSwagger2 //開啟swagger功能
@EnableSwaggerBootstrapUI // 開啟SwaggerBootstrapUI
public class SwaggerConfig {
    // 省略配置內容
}

3.訪問API：http://localhost:8080/doc.html，即可預覽到基於bootstarp的Swagger UI介面。

優點

1.?介面好看了一點

2.上面說過了，基於BootstrapUI的swagger支援指定form-data或x-www-form-urlencoded：

3.支援複製單個API文件和匯出全部API文件：

---

整合Spring Security注意

在Spring Boot整合Spring Security和Swagger的時候，需要配置攔截的路徑和放行的路徑，注意是放行以下幾個路徑。

.antMatchers("/swagger**/**").permitAll()
.antMatchers("/webjars/**").permitAll()
.antMatchers("/v2/**").permitAll()
.antMatchers("/doc.html").permitAll() // 如果你用了bootstarp的Swagger UI介面，加一個這個。

---

對於token的處理

在swagger中只支援了簡單的除錯，但對於一些介面，我們測試的時候可能需要把token資訊寫到header中，目前好像沒看到可以自定義加請求頭的地方？
?方法一：
　　如果你使用了Swagger BootstrapUI，那麼你可以在“文件管理”中增加全域性引數，這包括了新增header引數。

?方法二：在swagger配置類中增加全域性引數配置：

        //如果有額外的全域性引數，比如說請求頭引數，可以這樣新增
        ParameterBuilder parameterBuilder = new ParameterBuilder();
        List<Parameter> parameters = new ArrayList<Parameter>();
        parameterBuilder.name("authorization").description("令牌")
                .modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        parameters.add(parameterBuilder.build());
        return new Docket(DocumentationType.SWAGGER_2)  // DocumentationType.SWAGGER_2 固定的，代表swagger2
                .apiInfo(apiInfo()) // 用於生成API資訊
                .select() // select()函式返回一個ApiSelectorBuilder例項,用來控制介面被swagger做成文件
                .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 用於指定掃描哪個包下的介面
                .paths(PathSelectors.any())// 選擇所有的API,如果你想只為部分API生成文件，可以配置這裡
                .build().globalOperationParameters(parameters);

?方法三：使用@ApiImplicitParams來額外標註一個請求頭引數，例如：

    // 如果需要額外的引數，非本方法用到，但過濾器要用,類似於許可權token
    @PostMapping("/login6")
    @ApiOperation(value = "帶token的介面",notes = "帶token的介面")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "authorization",//引數名字
                    value = "授權token",//引數的描述
                    required = true,//是否必須傳入
                    paramType = "header"
            )
            ,
            @ApiImplicitParam(name = "username",//引數名字
                    value = "使用者名稱",//引數的描述
                    required = true,//是否必須傳入
                    paramType = "query"
            )
    })
    public String login6(String username){
        return username;
    }

---

Swagger的安全管理

1.如果你整合了許可權管理，可以給swagger加上許可權管理，要求訪問swagger頁面輸入使用者名稱和密碼，這些是spring security和shiro的事了，這裡不講。

2.如果你僅僅是不想在正式環境中可以訪問，可以在正式環境中關閉Swagger自動配置，這就不會有swagger頁面了。使用@Profile({"dev","test"})註解來限制只在dev或者test下啟用Swagger自動配置。
然後在Spring Boot配置檔案中修改當前profilespring.profiles.active=release，重啟之後，此時無法訪問http://localhost:8080/swagger-ui.html

---