Swagger使用總結

一. Swagger是什么？

Swagger是一款RESTFUL接口的文檔在線自動生成+功能測試功能軟件。

Swagger是一個規范和完整的框架,用於生成、描述、調用和可視化RESTful風格的Web服務。

swagger是一款可以根據resutful風格生成的生成的接口開發文檔，並且支持做測試的一款中間軟件

二：為什么要使用swaager?

2.1:對於后端開發人員來說

　　不用再手寫WiKi接口拼大量的參數，避免手寫錯誤

　　對代碼侵入性低，采用全注解的方式，開發簡單

　　方法參數名修改、增加、減少參數都可以直接生效，不用手動維護

　　缺點：增加了開發成本，寫接口還得再寫一套參數配置

2.2:對於前端開發來說

　　后端只需要定義好接口，會自動生成文檔，接口功能、參數一目了然

　　聯調方便，如果出問題，直接測試接口，實時檢查參數和返回值,就可以快速定位是前端還是后端的問題

2.3：對於測試

　　對於某些沒有前端界面UI的功能，可以用它來測試接口 

　　操作簡單，不用了解具體代碼就可以操作

三  :Swagger 解決了什么？

四：spring boot 集成 Swagger

4.1 ： pom文件引入Swagger依賴 如下

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

 4.2 ：編寫Swagger的配置啟動類,此類與springboot的啟動類同級目錄

Swagger啟動類代碼如下  啟動類中一定要配好掃描的contorller的全路徑

/**
 * swagger2的配置文件
 * http://localhost:30001/swagger-ui.html
 * @author songbin
 * @date 2019/5/28 15:37
 */
@Configuration
@EnableSwagger2
public class Swagger2 {
    /**
     * 配置swagger2的一些基本的內容，比如掃描的包等等
     * @return
     */
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ztqm.power.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 構建 api文檔的詳細信息函數
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //頁面標題
                .title("Welcome to Swagger2")
                //創建人
                .contact(new Contact("SongBin", "", "[e-mail]"))
                //版本號
                .version("1.0")
                //描述
                .description("您好 這里是 ：Swagger2的API文檔")
                .build();
    }

}

五：書寫Controller層 加入注解

/**
     * 網管實時報警表 添加操作
     * @param deviceAlarmProperty
     * @return
     */
    @ApiOperation(value = "添加 網管實時報警信息",notes = "根據DeviceAlarmProperty對象創建網管實時報警信息")
    @ApiImplicitParam(name = "deviceAlarmProperty",dataType = "DeviceAlarmProperty",value = "網管實時報警信息實體DeviceAlarmProperty")
    @RequestMapping(value = "/insert",method = RequestMethod.POST)
    public JsonUtil insert(DeviceAlarmProperty deviceAlarmProperty){
        int num = deviceAlarmPropertyService.insert(deviceAlarmProperty);
        //如果對象不為空 則重新賦默認值 code 1 ; msg  成功
        if(null != jsonUtil){
            jsonUtil = JsonUtil.getJsonUtil();
        }
        if(num==0){
            jsonUtil= JsonUtil.getError();
        }
        return jsonUtil;
    }

六：訪問 http://localhost:端口號/swagger-ui.html

點擊任意鏈接可以進行測試