Swagger使用簡介

在以前開發時，前端人員老是說：「調好的參數怎麼改了？接口不通了，能不能說一下」 html

我說：「1.文檔不夠詳情，我怎麼返回你所想要的數據　　2.我改完接口也告訴你了　　3.這樣吧！我之後改接口直接告訴你調式」前端

後來我看了一篇文章，既能夠解決先後端的矛盾，也能夠提升工做效率　　　　這就是Swaggerweb

一：swagger是什麼？spring

二：爲何使用swagger？編程

三：如何搭建一個swagger？json

四：在項目中如何集成swagger？後端

五：是那個用swagger須要注意的問題api

六：總結數組

一：Swagger是什麼？springboot

Swagger是一款RESTFUL接口的文檔在線自動生成+功能測試功能軟件。Swagger是一個規範和完整的框架，用於生成、描述、調用和可視化RESTfu風格的web服務。目標是使客戶端和文件系統做爲服務器一一樣的速度來更新文件的方法，參數和模型緊密集成到服務器。這個解釋簡單點來說就是說，swagger是一款能夠根據restful風格生成的接口開發文檔，而且支持作測試的一款中間軟件。

二：爲何使用swagger？

1.對於後端開發人員來講

不用再手寫Wiki接口拼大量參數，避免手寫錯誤
對代碼侵入性低，採用全註解的方式，開發簡單
方法參數名修改、新增、減小參數均可以直接生效，不用手動維護
缺點：增長了開發成本，寫接口還得再寫一套參數配置

2.對前端開發來講

後端只須要定義好接口，會自動生成文檔，接口功能、參數一目瞭然
聯調方便，若是出了問題，直接測試接口，實時檢查參數和返回值，就能夠快速定位是前端仍是後端的問題

3.對於測試

但對於測試沒有前端界面UI的功能，能夠直接用它來測試接口
操做簡單，不用瞭解具體代碼就能夠操做

三：如何搭建一個swagger？

在引入swagger的依賴，目前推薦使用2.7.0版本的，由於2.6.0版本有bug，而其餘版本有沒有經驗驗證

　　①引入swagger 依賴庫

　　　　<groupId>io.springfox</groupId>

　　　　<artifactId>springfox-swagger2</artifactId>

　　</dependency>

　　　　<groupId>io.springfox</groupId>

　　　　<artifactId>springfox-swagger-ui</artifactId>

　　</dependency>

　　②springboot整合swagger

@Configuration
@EnableSwagger2
public class SwaggerConfig {

 @Bean
 public Docket productApi(){
 return new Docket(DocumentationType.SWAGGER_2).
 apiInfo(apiInfo()).
 select().
 apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).//添加ApiOpentaion註解的被掃描
 paths(PathSelectors.any()).
 build();
 }

 private ApiInfo apiInfo(){
 return new ApiInfoBuilder().
 title("swagger和springboot整合").
 description("swagger的api文檔").
 version("1.0").build();
 }
}

swagger的註解：
swagger的核心在於註解，接下來就着重說一下swagger的註解

註解名稱	註解含義	註解使用地方	註解參數	參數含義
@EnableSwagger2	開啓swagger註解	配置類上	無	無
@Api	標識swagger識別的類	Controller類上	value tags description	url的路徑值若是設置這個值、value的值會被覆蓋對api資源的描述
@ApiIgore	屏蔽顯示某個Controller，開啓後在swagger上不會顯示	COntroller類上	value	值
@ApiOperation	標識swagger識別的方法	Controller類中的方法	value tags description basePath position produces consumes protocols authorizations hidden response responseContainer httpMethod code extensions notes	url的路徑值若是設置這個值、value的值會被覆蓋對api資源的描述基本路徑能夠不配置若是配置多個Api 想改變顯示順序位置 For example，"application/json，application/xml" For example，"application/json，application/xml" Possible values:http,https,ws,wss 高級特性認證時配置配置爲true將在文檔中隱藏返回的對象這些對象是有效的「List」，「Set」or 「Map」，其餘無效「GET」、「HEAD」、「POST」、「PUT」、「DELETE」、「OPTIONS」and "PATCh" http的狀態碼默認200 擴展屬性用於提示內容
@ApiImpliciParam	修飾方法中的參數	用在@ApiImplicitParams註解中對，指定一個請求參數的各個方面	paramType name value dataType required defaultValue	參數放在哪一個地方參數表明的含義參數名稱參數類型，有String/int，無用是否必要參數的默認值
@ApiImpliciParams	修飾方法中的參數	用在方法上包含一組參數說明	@ApiImpliciParam	ApiImpliciParam的數組集合
@ApiResponse	修飾方法的返回值	方法上或方法的參數上	code message class	方法返回值狀態碼方法返回值信息方法返回class
@ApiResponses	響應集配置	方法上或參數上	@ApiResponse	ApiResponse的數組集合
@ApiParam	映射方法上的參數	方法的參數上	name value defaultValue allowableValues required access allowMutiple hidden example	屬性名稱屬性值默認屬性值能夠不配置是否屬性必填不過多描述默認爲false 隱藏該屬性舉例子
@ApiModel	用於類，表示對類進行說明，用於參數用實體類接受	類上	value description	類名描述
@ApiModelProperty	標識一個類的屬性	類的字段上	value name dateType required example hidden	字段說明重寫屬性名字重寫屬性類型是否必填舉例子隱藏

四：在項目中如何集成swagger？

①在controller中使用註解

import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Api(value = "測試TTestController",tags = {"測試訪問接口"})
@RequestMapping("test")

public class TTestController {

    @ApiOperation(value = "添加測試數據")
    @PostMapping("/insertInfo")
    @ApiResponses(value = {
            @ApiResponse(code = 1000,message = "成功"),
            @ApiResponse(code = 1001,message = "失敗"),
            @ApiResponse(code = 1002,message = "缺乏參數",response = TestUser.class)
    })
    public String insertInfo(@ApiParam("用戶名字") @RequestParam("userName") String userName,
                             @ApiParam(value = "年齡",allowEmptyValue = true) @RequestParam("age") Integer age){
        String username = userName;
        Integer Age = age;
        return username+age.toString();
    }
}

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(value = "testUser",description = "用戶")
public class TestUser {

    @ApiModelProperty(value = "用戶名字", name = "userName", dataType = "String")
    private String userName;

    private Integer age;

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }

    public String getUserName() {
        return userName;
    }

    public void setUserName(String userName) {
        this.userName = userName;
    }
}

②訪問本地連接

http://localhost:8080/swagger-ui.html

五：是那個用swagger須要注意的問題

①:對於只有一個HttpServletRequest參數的方法,若是參數小於5個，推薦使用 @ApiImplicitParams的方式單獨封裝每個參數；若是參數大於5個，採用定義一個對象去封裝全部參數的屬性，而後使用@APiParam的方式

②默認的訪問地址：ip:port/swagger-ui.html#/,可是在shiro中,會攔截全部的請求，必須加上默認訪問路徑（好比項目中，就是
ip:port/context/swagger-ui.html#/），而後登錄後才能夠看到

③在GET請求中，參數在Body體裏面,不能使用@RequestBody。在POST請求，可使用@RequestBody和@RequestParam，若是使用@RequestBody，對於參數轉化的配置必須統一

④ controller必須指定請求類型，不然swagger會把全部的類型(6種)都生成出來

⑤: swagger在生產環境不能對外暴露,可使用@Profile({「dev」, 「prod」,「pre」})指定可使用的環境

六：總結

swagger做爲一款輔助性的工具，能大大提高咱們的和前端的溝通效率,接口是一個很是重要的傳遞數據的媒介，每一個接口的簽名、方法參數都很是重要。一個良好的文檔很是重要，若是採用手寫的方式很是容易拼寫錯誤，而swagger能夠自動化生成參數文檔，這一切都加快了咱們的溝通效率。而且能夠替代postman的做用。實在是開發編程必備良品啊。