springboot使用swagger2生成api文檔

一、為什么要用Swagger2？

之前開發項目的時候，需要寫API文檔，項目小接口少的時候一份word就能簡單應付，但是隨着項目的API的增加，對API文檔的維護工作就會越來越繁瑣，為此引入能自動生成RESTful接口文檔的Swagger2框架就變得理所當然。

作為一個能夠自動生成API文檔的框架，其最大的優點有兩個：

1. 接口文檔在線能夠自動生成，文檔隨接口變動實時更新，節省維護成本
2. 支持類似spring RESTful插件那樣的在線接口測試，不依賴第三方工具

二、舉個例子？

假設現在有一個TestController接口，里面有幾個簡單的API，通過swagger的注解添加接口描述

@Api(value = "Api-test", description = "測試接口")
@RequestMapping("/test/")
@RestController
public class TestController {
    
    @ApiOperation("獲取回復")
    @GetMapping("aiTalk")
    public String test(String str){
        str.replace("嗎？","");
        return str;
    }
	
    ... ... //下同，不再贅述
}

啟動項目后訪問特定頁面即可看到以Controller分類的API文檔，點擊展開以，根據注解的詳細程度，會有傳入參數，返回類型等詳細說明，除此之外，還會有類似springREST插件那樣的在線測試功能

三、如何在項目中引入swagger2？

1.引入Maven依賴

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

2.在springboot配置使用Swagger

/**
 * @Author：huang
 * @Date：2020-02-23 13:22
 * @Description：配置swagger2
 */
@EnableSwagger2
@Configuration
public class SwaggerConfiguration {
    @Bean
    public Docket adminApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
            .groupName("huangApi")
            .apiInfo(adminApiInfo())
            .select()
            .paths(Predicates.and(PathSelectors.regex("/.*")))
            .build();
    }

    private ApiInfo adminApiInfo(){
        return new ApiInfoBuilder()
            .title("簡單課程表-API文檔")
            .description("本文檔描述了簡單課程表系統的接口定義")
            .version("1.0")
            .build();
    }
}

3.訪問頁面

啟動項目，訪問 http://localhost:8080/swagger-ui.html#/ 即可

四、swagger2注解

1.@Api注解

用在請求的類上，表示對類的說明

屬性	作用
value	描述類的作用
tags	說明該類的作用，非空時將覆蓋value的值
protocols	設置特定協議，例：http， https， ws， wss
hidden	默認為false， 配置為true 將在文檔中隱藏

實例：

@Api(value = "Api-test", tags = "測試接口")
@RequestMapping("/test/")
@RestController
public class TestController {
    
}

2. @ApiOperation注解

用在請求的方法上，說明方法的用途、作用

屬性	作用
value	描述方法的作用
tags	說明該方法的作用，非空時將覆蓋value的值
response	返回對象類型（如果該對象類有@ApiModel屬性會在文檔的Model中列出）
httpMethod	指定HTTP方法，"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
hidden	默認為false， 配置為true 將在文檔中隱藏

實例：

@ApiOperation(value = "獲取課程表",response = CourseSchedule.class, httpMethod = "GET")
@RequestMapping(method = RequestMethod.GET, path =  "getCourseSchedule")
public CourseSchedule getCourseSchedule(){
    return new CourseSchedule();
}

3. @ApiImplicitParams注解

@ApiImplicitParam注解，用在@ApiImplicitParams注解中，表示一組參數的說明

@ApiParam注解，用在單個參數上，是對單個參數的說明

屬性	作用
value	參數的說明
name	參數名，參數名稱可以覆蓋方法參數名稱，路徑參數必須與方法參數一致
required	參數是否必須傳，默認為false(路徑參數必填)
defaultValue	參數的默認值
paramType	參數應該怎么傳給接口： 1.“header”對應spring@RequestHeader注解標記的參數； 2.“query”對應spring@RequestParam注解標記的參數； 3.“path”對應spring@PathVariable注解標記的參數；
dataType	參數類型

實例：

@ApiImplicitParams({
    @ApiImplicitParam(name = "str", value = "字符串", required = false, dataType = "String", paramType = "query"),
    @ApiImplicitParam(name = "id", value = "id", required = true, dataType = "Integer", paramType = "query")
})
@GetMapping(path =  "call")
public Result call(
    @ApiParam(name = "str", value = "字符串", required = false) String str,
    @ApiParam(name = "id", value = "id", required = true) Integer id){
    return Result.success("吱一聲以表示項目運行");
}

4. @ApiModel注解

用在請求的類上，表示對類的說明

@ApiModelProperty注解

用在被@ApiModel標記了的類的屬性上，用於描述類的屬性

注：此注解一般用於響應類上，比如使用@RequestBody注解直接接收對象作為參數的時候，多用於創建或更新

屬性	作用
value	此屬性的簡要說明
name	允許覆蓋屬性名稱
allowableValues	限制參數的可接受值，有以下幾種： 1.以逗號分隔的列表 2.范圍值 3.設置最小值/最大值
example	屬性的示例

實例：

/**
 * @Author：huang
 * @Date：2019-12-11 12:38
 * @Description：考試安排實體類
 */
@ApiModel("考試安排實體類")
public class ExamSchedule{

    @ApiModelProperty("課程名稱")
    private String courseName;

    @ApiModelProperty("考場")
    private String examClassroom;

    @ApiModelProperty("考試時間")
    private String examDate;

    @ApiModelProperty("當前時間")
    private String date;

    @ApiModelProperty("當前學期")
    private String nowDate;
}

另外，如果被標記的類有被 @ApiOperation注解的response屬性引用的話，在文檔頁面的Model可以看到

五、使用knife4j對swagger進行增強

1.什么是knife4？

knife4j是為JavaMVC框架集成Swagger生成Api文檔的增強解決方案 ，在Swagger的基礎上進行了各方面的增強，比如接口排序，一鍵導出markdown，word，pdf等功能，以及一個邏輯更加清晰而美觀的功能，最重要的是，這些實用功能不需要改動任何原有的注釋或者代碼，只需要加一個依賴！tql！！！

地址： https://doc.xiaominfo.com/

2.簡單使用

在原有swagger2依賴下引入knife4j依賴

<!--使用knife4j對swagger進行增強-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.1</version>
</dependency>

然后就可以用了！

沒錯，原本的 http://localhost:8080/swagger-ui.html#/ 頁面訪問完全不受影響，但是通過http://localhost:8080/doc.html即可訪問knife4j加強后的頁面，效果如下：