Swagger的介紹

🔶你可能嘗試過寫完一個接口后，自己去創(chuàng)建接口文檔，或者修改接口后修改接口文檔。多了之后，你肯定會發(fā)生一個操作，那就是忘記了修改文檔或者創(chuàng)建文檔（除非你們公司把接口文檔和寫接口要求得很緊密😓忘記寫文檔就扣工資？，否則兩個分離的工作總是有可能遺漏的）。而swagger就是一個在你寫接口的時候自動幫你生成接口文檔的東西，只要你遵循它的規(guī)范并寫一些接口的說明注解即可。

優(yōu)點與缺點

🔶優(yōu)點：

自動生成文檔，只需要在接口中使用注解進(jìn)行標(biāo)注，就能生成對應(yīng)的接口文檔。 自動更新文檔，由于是動態(tài)生成的，所以如果你修改了接口，文檔也會自動對應(yīng)修改（如果你也更新了注解的話）。這樣就不會發(fā)送我修改了接口，卻忘記更新接口文檔的情況。 支持在線調(diào)試，swagger提供了在線調(diào)用接口的功能。

🔶缺點：

不能創(chuàng)建測試用例，所以他暫時不能幫你處理完所有的事情。他只能提供一個簡單的在線調(diào)試，如果你想存儲你的測試用例，可以使用Postman或者YAPI這樣支持創(chuàng)建測試用戶的功能。 要遵循一些規(guī)范，它不是任意規(guī)范的。比如說，你可能會返回一個json數(shù)據(jù)，而這個數(shù)據(jù)可能是一個Map格式的，那么我們此時不能標(biāo)注這個Map格式的返回數(shù)據(jù)的每個字段的說明，而如果它是一個實體類的話，我們可以通過標(biāo)注類的屬性來給返回字段加說明。也比如說，對于swagger，不推薦在使用GET方式提交數(shù)據(jù)的時候還使用Body，僅推薦使用query參數(shù)、header參數(shù)或者路徑參數(shù)，當(dāng)然了這個限制只適用于在線調(diào)試。 沒有接口文檔更新管理，雖然一個接口更新之后，可能不會關(guān)心舊版的接口信息，但你“可能”想看看舊版的接口信息，例如有些灰度更新發(fā)布的時候可能還會關(guān)心舊版的接口。那么此時只能由后端去看看有沒有注釋留下了，所以可以考慮接口文檔大更新的時候注釋舊版的，然后寫下新版的。【當(dāng)然這個問題可以通過導(dǎo)出接口文檔來對比。】 雖然現(xiàn)在Java的實體類中有不少模型，po,dto,vo等，模型的區(qū)分是為了屏蔽一些多余參數(shù)，比如一個用戶登錄的時候只需要username,password，但查權(quán)限的時候需要連接上權(quán)限表的信息，而如果上述兩個操作都是使用了User這個實體的話，在文檔中就會自動生成了多余的信息，這就要求了你基于模型來創(chuàng)建多個實體類，比如登錄的時候一個LoginForm，需要用戶-權(quán)限等信息的時候才使用User類。（當(dāng)然了，這個問題等你會swagger之后你就大概就會怎么規(guī)避這個問題了。）

😓上面的缺點好像寫的有點多，你可能會覺得swagger這個坑有點大。但其實主要是規(guī)范問題，而規(guī)范問題有時候又會提高你的代碼規(guī)范性，這個就見仁見智了，你以前可能什么接口的參數(shù)都使用一個類，而現(xiàn)在swagger要求你分開后，某種層次上提高了你的代碼規(guī)范性。

🔶注：以下代碼示例基于Spring Boot。完整代碼可以參考：swagger-demo

添加swagger

💡這里先講添加swagger，也就是先整合進(jìn)來，至于怎么使用，下面的“場景”中再講解。

1.添加依賴包：

❗注意，這里的前提是已經(jīng)導(dǎo)入了spring boot的web包。

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

2.配置Swagger:

要使用swagger，我們必須對swagger進(jìn)行配置，我們需要創(chuàng)建一個swagger的配置類，比如可以命名為SwaggerConfig.java

package com.example.config;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.service.ApiInfo;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration // 標(biāo)明是配置類@EnableSwagger2 //開啟swagger功能public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) // DocumentationType.SWAGGER_2 固定的，代表swagger2// .groupName('分布式任務(wù)系統(tǒng)') // 如果配置多個文檔的時候，那么需要配置groupName來分組標(biāo)識 .apiInfo(apiInfo()) // 用于生成API信息 .select() // select()函數(shù)返回一個ApiSelectorBuilder實例,用來控制接口被swagger做成文檔 .apis(RequestHandlerSelectors.basePackage('com.example.controller')) // 用于指定掃描哪個包下的接口 .paths(PathSelectors.any())// 選擇所有的API,如果你想只為部分API生成文檔，可以配置這里 .build(); } /** * 用于定義API主界面的信息，比如可以聲明所有的API的總標(biāo)題、描述、版本 * @return */ private ApiInfo apiInfo() { return new ApiInfoBuilder() .title('XX項目API') // 可以用來自定義API的主標(biāo)題 .description('XX項目SwaggerAPI管理') // 可以用來描述整體的API .termsOfServiceUrl('') // 用于定義服務(wù)的域名 .version('1.0') // 可以用來定義版本。 .build(); // }}

3.測試

運行我們的Spring Boot項目，（我默認(rèn)是8080端口，如果你不一樣，請注意修改后續(xù)的url），訪問http://localhost:8080/swagger-ui.html然后你就可以看到一個如下的界面，由于我們暫時沒有配置接口數(shù)據(jù)，所以下面顯示No operations defined in spec!

💡下面我們將介紹如何定義接口，以及在swagger UI界面中的內(nèi)容。

場景：

定義接口組

接口有時候應(yīng)該是分組的，而且大部分都是在一個controller中的，比如用戶管理相關(guān)的接口應(yīng)該都在UserController中，那么不同的業(yè)務(wù)的時候，應(yīng)該定義/劃分不同的接口組。接口組可以使用@Api來劃分。比如：

@Api(tags = '角色管理') // tags：你可以當(dāng)作是這個組的名字。@RestControllerpublic class RoleController {}

和

@Api(tags = '用戶管理') // tags：你可以當(dāng)作是這個組的名字。@RestControllerpublic class UserController {}

🔵你也可以理解成基于tags來分組，就好像一些文章里面的標(biāo)簽一樣，使用標(biāo)簽來分類。🔵如果這個Controller下（接口組）下面沒有接口，那么在swagger ui中是不會顯示的，如果有的話就會這樣顯示：

定義接口

使用了@Api來標(biāo)注一個Controller之后，如果下面有接口，那么就會默認(rèn)生成文檔，但沒有我們自定義的說明：

@Api(tags = '用戶管理')@RestControllerpublic class UserController { // 注意，對于swagger，不要使用@RequestMapping， // 因為@RequestMapping支持任意請求方式，swagger會為這個接口生成7種請求方式的接口文檔 @GetMapping('/info') public String info(String id){ return 'aaa'; }}

我們可以使用@ApiOperation來描述接口，比如：

@ApiOperation(value = '用戶測試',notes = '用戶測試notes') @GetMapping('/test') public String test(String id){ return 'test'; }

常用配置項：

value：可以當(dāng)作是接口的簡稱notes：接口的描述 tags：可以額外定義接口組，比如這個接口外層已經(jīng)有@Api(tags = '用戶管理')，將接口劃分到了“用戶管理”中，但你可以額外的使用 tags，例如tags = '角色管理'讓角色管理中也有這個接口文檔。

定義接口請求參數(shù)

上面使用了@ApiOperation來了描述接口，但其實還缺少接口請求參數(shù)的說明，下面我們分場景來講。🔵注意一下，對于GET方式，swagger不推薦使用body方式來傳遞數(shù)據(jù)，也就是不希望在GET方式時使用json、form-data等方式來傳遞，這時候最好使用路徑參數(shù)或者url參數(shù)。(😓雖然POSTMAN等是支持的)，所以如果接口傳遞的數(shù)據(jù)是json或者form-data方式的，還是使用POST方式好。

場景一：請求參數(shù)是實體類。

此時我們需要使用@ApiModel來標(biāo)注實體類，然后在接口中定義入?yún)閷嶓w類即可：

@ApiModel：用來標(biāo)類

常用配置項：

value：實體類簡稱

description：實體類說明

@ApiModelProperty：用來描述類的字段的意義。

常用配置項：

value：字段說明

example：設(shè)置請求示例（Example Value）的默認(rèn)值，如果不配置，當(dāng)字段為string的時候，此時請求示例中默認(rèn)值為''.name：用新的字段名來替代舊的字段名。

allowableValues：限制值得范圍，例如{1,2,3}代表只能取這三個值；[1,5]代表取1到5的值；(1,5)代表1到5的值，不包括1和5；還可以使用infinity或-infinity來無限值，比如[1, infinity]代表最小值為1，最大值無窮大。

required：標(biāo)記字段是否必填，默認(rèn)是false,

hidden：用來隱藏字段，默認(rèn)是false，如果要隱藏需要使用true，因為字段默認(rèn)都會顯示，就算沒有@ApiModelProperty。

// 先使用@ApiModel來標(biāo)注類@ApiModel(value='用戶登錄表單對象',description='用戶登錄表單對象')public class LoginForm { // 使用ApiModelProperty來標(biāo)注字段屬性。 @ApiModelProperty(value = '用戶名',required = true,example = 'root') private String username; @ApiModelProperty(value = '密碼',required = true,example = '123456') private String password; // 此處省略入?yún)①x值時需要的getter,setter,swagger也需要這個}

定義成入?yún)ⅲ?/p>

@ApiOperation(value = '登錄接口',notes = '登錄接口的說明') @PostMapping('/login') public LoginForm login(@RequestBody LoginForm loginForm){ return loginForm; }

效果：

場景二：請求參數(shù)是非實體類。

（再說一次：對于GET方式，swagger不推薦使用body方式來傳遞數(shù)據(jù)，所以雖然Spring MVC可以自動封裝參數(shù)，但對于GET請求還是不要使用form-data，json等方式傳遞參數(shù)，除非你使用Postman來測試接口，swagger在線測試是不支持這個操作的）

對于非實體類參數(shù)，可以使用@ApiImplicitParams和@ApiImplicitParam來聲明請求參數(shù)。@ApiImplicitParams用在方法頭上，@ApiImplicitParam定義在@ApiImplicitParams里面，一個@ApiImplicitParam對應(yīng)一個參數(shù)。@ApiImplicitParam常用配置項：

name：用來定義參數(shù)的名字，也就是字段的名字,可以與接口的入?yún)⒚麑?yīng)。如果不對應(yīng)，也會生成，所以可以用來定義額外參數(shù)！ value：用來描述參數(shù) required：用來標(biāo)注參數(shù)是否必填 paramType有path,query,body,form,header等方式，但對于對于非實體類參數(shù)的時候，常用的只有path,query,header；body和form是不常用的。body不適用于多個零散參數(shù)的情況，只適用于json對象等情況。【如果你的接口是form-data,x-www-form-urlencoded的時候可能不能使用swagger頁面API調(diào)試，但可以在后面講到基于BootstrapUI的swagger增強中調(diào)試，基于BootstrapUI的swagger支持指定form-data或x-www-form-urlencoded】

示例一：聲明入?yún)⑹荱RL參數(shù)

// 使用URL query參數(shù) @ApiOperation(value = '登錄接口2',notes = '登錄接口的說明2') @ApiImplicitParams({ @ApiImplicitParam(name = 'username',//參數(shù)名字 value = '用戶名',//參數(shù)的描述 required = true,//是否必須傳入 //paramType定義參數(shù)傳遞類型：有path,query,body,form,header paramType = 'query' ) , @ApiImplicitParam(name = 'password',//參數(shù)名字 value = '密碼',//參數(shù)的描述 required = true,//是否必須傳入 paramType = 'query' ) }) @PostMapping(value = '/login2') public LoginForm login2(String username,String password){ System.out.println(username+':'+password); LoginForm loginForm = new LoginForm(); loginForm.setUsername(username); loginForm.setPassword(password); return loginForm; }

示例二：聲明入?yún)⑹荱RL路徑參數(shù)

// 使用路徑參數(shù) @PostMapping('/login3/{id1}/{id2}') @ApiOperation(value = '登錄接口3',notes = '登錄接口的說明3') @ApiImplicitParams({ @ApiImplicitParam(name = 'id1',//參數(shù)名字 value = '用戶名',//參數(shù)的描述 required = true,//是否必須傳入 //paramType定義參數(shù)傳遞類型：有path,query,body,form,header paramType = 'path' ) , @ApiImplicitParam(name = 'id2',//參數(shù)名字 value = '密碼',//參數(shù)的描述 required = true,//是否必須傳入 paramType = 'path' ) }) public String login3(@PathVariable Integer id1,@PathVariable Integer id2){ return id1+':'+id2; }

示例三：聲明入?yún)⑹莌eader參數(shù)

// 用header傳遞參數(shù) @PostMapping('/login4') @ApiOperation(value = '登錄接口4',notes = '登錄接口的說明4') @ApiImplicitParams({ @ApiImplicitParam(name = 'username',//參數(shù)名字 value = '用戶名',//參數(shù)的描述 required = true,//是否必須傳入 //paramType定義參數(shù)傳遞類型：有path,query,body,form,header paramType = 'header' ) , @ApiImplicitParam(name = 'password',//參數(shù)名字 value = '密碼',//參數(shù)的描述 required = true,//是否必須傳入 paramType = 'header' ) }) public String login4( @RequestHeader String username, @RequestHeader String password){ return username+':'+password; }

示例四：聲明文件上傳參數(shù)

// 有文件上傳時要用@ApiParam，用法基本與@ApiImplicitParam一樣，不過@ApiParam用在參數(shù)上 // 或者你也可以不注解，swagger會自動生成說明 @ApiOperation(value = '上傳文件',notes = '上傳文件') @PostMapping(value = '/upload') public String upload(@ApiParam(value = '圖片文件', required = true)MultipartFile uploadFile){ String originalFilename = uploadFile.getOriginalFilename(); return originalFilename; } // 多個文件上傳時，**swagger只能測試單文件上傳** @ApiOperation(value = '上傳多個文件',notes = '上傳多個文件') @PostMapping(value = '/upload2',consumes = 'multipart/*', headers = 'content-type=multipart/form-data') public String upload2(@ApiParam(value = '圖片文件', required = true,allowMultiple = true)MultipartFile[] uploadFile){ StringBuffer sb = new StringBuffer(); for (int i = 0; i < uploadFile.length; i++) { System.out.println(uploadFile[i].getOriginalFilename()); sb.append(uploadFile[i].getOriginalFilename()); sb.append(','); } return sb.toString(); } // 既有文件，又有參數(shù) @ApiOperation(value = '既有文件，又有參數(shù)',notes = '既有文件，又有參數(shù)') @PostMapping(value = '/upload3') @ApiImplicitParams({ @ApiImplicitParam(name = 'name', value = '圖片新名字', required = true ) }) public String upload3(@ApiParam(value = '圖片文件', required = true)MultipartFile uploadFile, String name){ String originalFilename = uploadFile.getOriginalFilename(); return originalFilename+':'+name; }

定義接口響應(yīng)

定義接口響應(yīng)，是方便查看接口文檔的人能夠知道接口返回的數(shù)據(jù)的意義。

響應(yīng)是實體類：

前面在定義接口請求參數(shù)的時候有提到使用@ApiModel來標(biāo)注類，如果接口返回了這個類，那么這個類上的說明也會作為響應(yīng)的說明：

// 返回被@ApiModel標(biāo)注的類對象 @ApiOperation(value = '實體類響應(yīng)',notes = '返回數(shù)據(jù)為實體類的接口') @PostMapping('/role1') public LoginForm role1(@RequestBody LoginForm loginForm){ return loginForm; }

響應(yīng)是非實體類：

swagger無法對非實體類的響應(yīng)進(jìn)行詳細(xì)說明，只能標(biāo)注響應(yīng)碼等信息。是通過@ApiResponses和@ApiResponse來實現(xiàn)的。@ApiResponses和@ApiResponse可以與@ApiModel一起使用。

// 其他類型的,此時不能增加字段注釋，所以其實swagger推薦使用實體類 @ApiOperation(value = '非實體類',notes = '非實體類') @ApiResponses({ @ApiResponse(code=200,message = '調(diào)用成功'), @ApiResponse(code=401,message = '無權(quán)限' ) } ) @PostMapping('/role2') public String role2(){ return ' {n' + ' name:'廣東',n' + ' citys:{n' + ' city:['廣州','深圳','珠海']n' + ' }n' + ' }'; }

Swagger UI增強

你可能會覺得現(xiàn)在這個UI不是很好看，現(xiàn)在有一些第三方提供了一些Swagger UI增強，比較流行的是swagger-bootstrap-ui，我們這里以swagger-bootstrap-ui為例。

UI對比：

使用

1.添加依賴包：

<!--引入swagger--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> <!-- 引入swagger-bootstrap-ui依賴包--> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.8.7</version> </dependency>

2.在swagger配置類中增加注解@EnableSwaggerBootstrapUI:

@Configuration // 標(biāo)明是配置類@EnableSwagger2 //開啟swagger功能@EnableSwaggerBootstrapUI // 開啟SwaggerBootstrapUIpublic class SwaggerConfig { // 省略配置內(nèi)容}

3.訪問API：http://localhost:8080/doc.html，即可預(yù)覽到基于bootstarp的Swagger UI界面。

優(yōu)點

1.🤔界面好看了一點

2.上面說過了，基于BootstrapUI的swagger支持指定form-data或x-www-form-urlencoded：

3.支持復(fù)制單個API文檔和導(dǎo)出全部API文檔：

整合Spring Security注意

在Spring Boot整合Spring Security和Swagger的時候，需要配置攔截的路徑和放行的路徑，注意是放行以下幾個路徑。

.antMatchers('/swagger**/**').permitAll().antMatchers('/webjars/**').permitAll().antMatchers('/v2/**').permitAll().antMatchers('/doc.html').permitAll() // 如果你用了bootstarp的Swagger UI界面，加一個這個。

對于token的處理

在swagger中只支持了簡單的調(diào)試，但對于一些接口，我們測試的時候可能需要把token信息寫到header中，目前好像沒看到可以自定義加請求頭的地方？💡方法一：如果你使用了Swagger BootstrapUI，那么你可以在“文檔管理”中增加全局參數(shù)，這包括了添加header參數(shù)。

💡方法二：在swagger配置類中增加全局參數(shù)配置：

//如果有額外的全局參數(shù)，比如說請求頭參數(shù)，可以這樣添加 ParameterBuilder parameterBuilder = new ParameterBuilder(); List<Parameter> parameters = new ArrayList<Parameter>(); parameterBuilder.name('authorization').description('令牌') .modelRef(new ModelRef('string')).parameterType('header').required(false).build(); parameters.add(parameterBuilder.build()); return new Docket(DocumentationType.SWAGGER_2) // DocumentationType.SWAGGER_2 固定的，代表swagger2 .apiInfo(apiInfo()) // 用于生成API信息 .select() // select()函數(shù)返回一個ApiSelectorBuilder實例,用來控制接口被swagger做成文檔 .apis(RequestHandlerSelectors.basePackage('com.example.controller')) // 用于指定掃描哪個包下的接口 .paths(PathSelectors.any())// 選擇所有的API,如果你想只為部分API生成文檔，可以配置這里 .build().globalOperationParameters(parameters);

💡方法三：使用@ApiImplicitParams來額外標(biāo)注一個請求頭參數(shù)，例如：

// 如果需要額外的參數(shù)，非本方法用到，但過濾器要用,類似于權(quán)限token @PostMapping('/login6') @ApiOperation(value = '帶token的接口',notes = '帶token的接口') @ApiImplicitParams({ @ApiImplicitParam(name = 'authorization',//參數(shù)名字 value = '授權(quán)token',//參數(shù)的描述 required = true,//是否必須傳入 paramType = 'header' ) , @ApiImplicitParam(name = 'username',//參數(shù)名字 value = '用戶名',//參數(shù)的描述 required = true,//是否必須傳入 paramType = 'query' ) }) public String login6(String username){ return username; }

Swagger的安全管理

1.如果你整合了權(quán)限管理，可以給swagger加上權(quán)限管理，要求訪問swagger頁面輸入用戶名和密碼，這些是spring security和shiro的事了，這里不講。

2.如果你僅僅是不想在正式環(huán)境中可以訪問，可以在正式環(huán)境中關(guān)閉Swagger自動配置，這就不會有swagger頁面了。使用@Profile({'dev','test'})注解來限制只在dev或者test下啟用Swagger自動配置。然后在Spring Boot配置文件中修改當(dāng)前profilespring.profiles.active=release，重啟之后，此時無法訪問http://localhost:8080/swagger-ui.html

到此這篇關(guān)于Spring Boot整合swagger使用教程的文章就介紹到這了,更多相關(guān)Spring Boot整合swagger內(nèi)容請搜索好吧啦網(wǎng)以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持好吧啦網(wǎng)！