swagger管理介面工程簡單搭建

2022-09-14 02:00:13 字數 3600 閱讀 6915

簡介：swagger是一種rest api的 簡單但強大的表示方式，標準的，語言無關，這種 表示方式不但人可讀，而且機器可讀。 可以作為rest api的互動式文件，也可以作為rest api的形式化的介面描述，生成客戶端和服務端的**。

下面結合比較常見的場景，大概說下在springboot下如何使用swagger來管理介面，以便前後端開發人員能夠很好的做介面的對接，同時也利於介面的後續維護開發。

1. 在pom.xml引入swagger所需依賴包：

1


2<


dependency


>


3<


groupid


>io.springfox


groupid


>


4<


artifactid


>springfox-swagger2


artifactid


>


5dependency


>67


<


dependency


>


8<


groupid


>io.springfox


groupid


>


9<


artifactid


>springfox-swagger-ui


artifactid


>


10dependency


>


11
2.指定swagger的一些靜態資源檔案配置，一般用乙個類來管理維護

swagger2configuration.class

1


import org.springframework.context.annotation.bean;


2import org.springframework.context.annotation.configuration;


3import springfox.documentation.builders.apiinfobuilder;


4import springfox.documentation.builders.pathselectors;


5import springfox.documentation.builders.requesthandlerselectors;


6import springfox.documentation.service.apiinfo;


7import springfox.documentation.spi.documentationtype;


8import springfox.documentation.spring.web.plugins.docket;


9import springfox.documentation.swagger2.annotations.enableswagger2;


1011


12 @configuration


13 @enableswagger2


14public


class swagger2configuration 


2425


private apiinfo apiinfo() 


3334 }
3. 如何使用？

這一步我會用比較常見的業務場景去描述介面：

其實通過單獨建乙個api介面讓controller去實現它，避免大量註解內容讓controller看著太亂

這裡直接在controller層（類）上這樣註解

1 @api(value = "swagger介面")


2 @restcontroller


4public


class swaggercontroller)


13public user find (@modelattribute user user) 


16 }
其中user類如下：

1


//@apimodel(value="user", description="使用者物件") 


2public


class user 


12public


void setname(string name) 


15public


void setage(long age) 


18public long getid() 


21public string getname() 


24public long getage() 


2728 }


2930
user類是對應查詢條件或查詢結果組成的實體~，每個屬性需要用@apimodelproperty去描述每個欄位的含義；user類上的@apimodel註解可以選擇性給出。

訪問swagger介面描述頁面只需啟動專案（這裡是springboot），然後輸入http://localhost:8080/swagger-ui.html#!即可訪問，我們點選對應的controller和介面，可以看到：

paramters就是描述輸入引數的區域，而response則是輸出的描述，response可以切換到model，可以看到輸出的字段的具體含義：

2）請求引數是復合的，這時候必須對應乙個實體類，如：

1


//@apimodel(value="params", description="傳入引數") 


2public


class params 


1213


public


void setparam1(string param1) 


1617


public listgetinput() 


2021


public


void setinput(listinput) 


2425 }
返回是乙個集合型別：

1 @apioperation(value="獲取使用者資訊集合", notes="根據輸入型別來獲取使用者資訊集合")


3 @apiresponse(response = user.class, responsecontainer="list", code = 200, message = "請求成功")


4public listfind2(@apiparam(value="傳入引數型別", required=true) @requestbody params params) 


可以看到，現在無論是對於介面裡再複雜的輸入和輸出，都能比較清楚地看到每個屬性（字段）的含義，以及可以在swagger的ui上直接用try it out 按鈕來測試介面的可用性。


swagger可以很好地幫助我們管理專案介面~，以及不同業務側之間的介面對接工作。
 
swagger管理後台介面
swagger 是乙個rest apis文件生成工具。1.swagger可是直接嵌入到專案中，在介面上加上介面的註解描述，自動生成介面文件。2.很方便管理和測試後台介面。下面是swagger的基礎配置 configuration enableswagger2 public class swagger...


Swagger介面文件
api 用在類上，說明該類的作用。apioperation 註解來給api增加方法說明。apiimplicitparams 用在方法上包含一組引數說明。apiimplicitparam 用來註解來給方法入參增加說明。apiresponses 用於表示一組響應 apiresponse 用在 apire...


swagger 介面測試
廢話不多說，直接上 1 pom 新增 io.springfox springfox swagger2 2.8.0 io.springfox springfox swagger ui 2.8.0 2 增加swaggerconfig package com.test.service1 date 2020...