SpringBoot集成Swagger以及Knife4j

本文基於 SpringBoot 進行的集成

集成 Swagger

集成的步驟就幾步，首先引入 swagger springboot 啟動器依賴，修改 pom.xml：

<!--swagger-->
<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.8.0.RELEASE</version>
</dependency>

當然你可以把 swagger 抽離成一個類似和 common 作用一樣的模塊公共模塊，就是某個微服務需要使用 swagger 依賴一下 swagger 模塊即可完成這里不演示這個這里只是記錄一下集成 swagger 以及它所對應的皮膚緊接着修改 application.yml 添加如下內容：

#自定義 swagger信息
swagger:
  base-package: top.it6666
  description: BNTang相關接口API文檔
  title: BNTangAPI
  version: 1.0

修改啟動類啟動 swagger：

/**
 * @author BNTang
 * @program myDemoPro
 * @date Created in 2021/10/25 025 14:15
 * @description
 * - swagger文檔地址：http://localhost:8081/swagger-ui.html
 **/
@SpringBootApplication
@EnableSwagger2Doc
public class SwaggerApp {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApp.class, args);
    }
}

然后可以添加一個 Controller 進行測試創建 TestController.java 內容如下：

/**
 * 測試控制器
 *
 * @author BNTang
 * @date 2021/10/25
 */
@RestController
@RequestMapping("/swagger/test")
@Api(tags = "測試API接口")
public class TestController {

    @GetMapping("/getList")
    @ApiOperation(value = "獲取列表數據", notes = "獲取列表下測試數據")
    public String list() {
        return "查詢列表數據!";
    }

    @GetMapping("{id}")
    @ApiOperation(value = "獲取ID數據", notes = "根據ID獲取某條測試數據")
    @ApiImplicitParam(name = "id", value = "主鍵id", paramType = "path", required = true)
    public String find(@PathVariable Integer id) {
        return String.format("根據主鍵查詢數據: %d", id);
    }

    @PostMapping("/add")
    @ApiOperation(value = "新增數據")
    @ApiParam(name = "test", value = "添加的測試模型實體")
    public String add(@RequestBody Test test) {
        System.out.println(test);
        return "插入數據!";
    }

    @PutMapping("{id}")
    @ApiOperation(value = "更新數據", notes = "根據ID更新測試數據")
    @ApiImplicitParam(name = "id", value = "主鍵id", paramType = "path", required = true)
    public String update(@PathVariable Integer id,
                         @ApiParam(name = "test", value = "更新的測試模型實體") @RequestBody Test test) {
        System.out.println(test);
        return String.format("根據主鍵更新一條記錄: %d", id);
    }

    @DeleteMapping("{id}")
    @ApiOperation(value = "刪除數據", notes = "根據ID刪除測試數據")
    @ApiImplicitParam(name = "id", value = "主鍵id", paramType = "path", required = true)
    public String delete(@PathVariable Integer id) {
        return String.format("根據主鍵刪除記錄: %d", id);
    }
}

創建 Test.java 實體類：

/**
 * @author BNTang
 * @program myDemoPro
 * @date Created in 2021/10/25 025 14:51
 * @description
 **/
@Data
public class Test {
    private String name;
}

如上的實體類當中使用到了 lombok 相關的內容所以你可以依賴一下添加如下依賴：

<!--lombok插件-->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
</dependency>

緊接着啟動工程訪問：host:port/swagger-ui.html 效果如下：

Swagger 漢化

• https://www.cnblogs.com/BNTang/articles/14586128.html

集成 Knife4j

通過上圖發現 swagger 自帶的 UI 不美觀，但是呢，有一些開源的愛好的專門開發的一款 Knife4j 的皮膚來美化一下如上的界面同時也進行的增強，如下就是集成的過程和記錄首先引入依賴：

<!--knife4j,swagger皮膚-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.6</version>
</dependency>

修改啟動類：

/**
 * @author BNTang
 * @program myDemoPro
 * @date Created in 2021/10/25 025 14:15
 * @description
 * - knife4j文檔地址：http://localhost:8081/doc.html#/home
 * - swagger文檔地址：http://localhost:8081/swagger-ui.html
 **/
@SpringBootApplication
@EnableSwagger2Doc
@EnableKnife4j
public class SwaggerApp {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApp.class, args);
    }
}

在這里我強調一個問題就是如上我說過一個東西你可以把 swagger 抽離成和 common 類似的小模塊，如果需要使用 swagger 依賴一下即可，如上這個修改的啟動類修改的是依賴 swagger 模塊的啟動類開啟一下 Knife4j 我這里沒有演示這個場景你就大概去理解一下，不懂你可以下方留言。經過了如上的配置之后再次啟動工程訪問：host:port/doc.html 效果如下圖所示：

如有不誤，請指出🐤

源碼下載地址：https://gitee.com/BNTang/my-demo-pro