實戰(zhàn)分布式醫(yī)療掛號系統(tǒng)之整合Swagger2到通用模塊

更新時間：2022年04月24日 15:44:09 作者：Hudie.

這篇文章主要為大家介紹了實戰(zhàn)分布式醫(yī)療掛號系統(tǒng)之整合Swagger2到通用模塊，有需要的朋友可以借鑒參考下，希望能夠有所幫助，祝大家多多進步，早日升職加薪

文章導讀

本系列文章介紹從0開始搭建一個基于分布式的醫(yī)療掛號系統(tǒng)。本次四篇文章完成了醫(yī)院設置微服務模塊的后端接口，為了方便開發(fā)，對接口的返回結果、全局異常、全局日志進行了統(tǒng)一處理。同時，為了方便進行訪問測試，還整合了Swagger2工具，這些通用的模塊中，除了全局日志被放在醫(yī)院設置微服務模塊的配置資源中，其余都統(tǒng)一被抽取在common模塊中。具體實現可參考下面文章：

醫(yī)院設置微服務 | 模塊搭建

醫(yī)院設置微服務 | 接口開發(fā)

通用模塊 | 統(tǒng)一返回結果、統(tǒng)一異常處理、統(tǒng)一日志處理

項目已開源至 https://github.com/Guoqianliang/yygh_parent

在使用REST風格進行接口的開發(fā)測試時，post請求無法使用瀏覽器直接進行訪問測試，目前流行的解決方案是使用Swagger2。Swagger2是一個API接口文檔，通過Swagger2可以方便各種提交方式的接口測試。

通過Swagger2，我們可以看到接口名稱、請求方法、傳遞參數、返回信息等。

通用模塊整合swagger2步驟

本項目中，眾多的微服務都需要整合Swagger2，所以我將其依賴引入在了通用的common父模塊中，配置在common_util模塊中。

1.引入swagger依賴

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

2.配置Swagger2

如下的Swagger2配置信息中分別創(chuàng)建了webApi分組和adminApi分組的Bean。

/**
 * Swagger2配置信息
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket webApiConfig() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                //只顯示api路徑下的頁面
                .paths(Predicates.and(PathSelectors.regex("/api/.*")))
                .build();
    }
    @Bean
    public Docket adminApiConfig() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("adminApi")
                .apiInfo(adminApiInfo())
                .select()
                //只顯示admin路徑下的頁面
                .paths(Predicates.and(PathSelectors.regex("/admin/.*")))
                .build();
    }
    private ApiInfo webApiInfo() {
        return new ApiInfoBuilder()
                .title("網站-API文檔")
                .description("本文檔描述了網站微服務接口定義")
                .version("1.0")
                .contact(new Contact("gql", "http://gql.com", "guoqianliang@foxmail.com"))
                .build();
    }
    private ApiInfo adminApiInfo() {
        return new ApiInfoBuilder()
                .title("后臺管理系統(tǒng)-API文檔")
                .description("本文檔描述了后臺管理系統(tǒng)微服務接口定義")
                .version("1.0")
                .contact(new Contact("gql", "http://gql.com", "guoqianliang@foxmail.com"))
                .build();
    }
}

3.啟動類添加包掃描

Swagger2的配置類寫好了，現在需要在service_host模塊使用配置類。由于二者不在同一個項目中，所以需要在service_host模塊的父模塊的pom中引入service_util。

而兩者包名不同，還需要額外在啟動類上添加包掃描。

引入swagger配置類

測試

項目啟動后訪問：http://localhost:8201/swagger-ui.html ，可以看到項目中接口的信息：

通過swagger查看后臺API文檔

在Controller中添加下面幾個簡單的Api注解，可以將swagger中的一些信息定義為中文：

通過swagger添加注解

如果需要測試接口，我們只需要點擊接口下方的Try it out 按鈕：

通過swagger測試方法

點擊按鈕后即可，看到接口的一系列返回信息：

通過swagger查看方法返回結果

swagger常用注解

注解	說明
@Api	修飾整個類，描述Controller的作用
@ApiOperation	描述一個類的一個方法，或者說一個接口
@ApiParam	單個參數描述
@ApiModel	用對象來接收參數
@ApiModelProperty	用對象接收參數時，描述對象的一個字段
@ApiImplicitParam	一個請求參數
@ApiImplicitParams	多個請求參數