快捷導(dǎo)航

springboot如何集成Swagger2

更新時(shí)間：2020年12月18日 11:29:28 作者：Tom-shushu

這篇文章主要介紹了springboot集成Swagger2的方法，幫助大家更好的理解和使用springboot框架，感興趣的朋友可以了解下

一、是什么

　　當(dāng)下很多公司都采取前后端分離的開發(fā)模式，前端和后端的工作由不同的工程師完成。在這種開發(fā)模式下，維持一份及時(shí)更新且完整的 Rest API 文檔將會(huì)極大的提高我們的工作效率。傳統(tǒng)意義上的文檔都是后端開發(fā)人員手動(dòng)編寫的，相信大家也都知道這種方式很難保證文檔的及時(shí)性，這種文檔久而久之也就會(huì)失去其參考意義，反而還會(huì)加大我們的溝通成本。而 Swagger 給我們提供了一個(gè)全新的維護(hù) API 文檔的方式。

二、為什么要使用它

　　1、代碼變更，文檔跟著代碼變、只需要少量的注解Swagger就可以根據(jù)代碼自動(dòng)的生成API文檔，很好的保證了文檔的實(shí)時(shí)性。

　　2、跨語(yǔ)言，Swagger支持40多種語(yǔ)言。

　　3、Swagger UI 呈現(xiàn)出來(lái)的是一份可以交互的API文檔，我們可以直接在文檔頁(yè)面嘗試API的調(diào)用，省去了準(zhǔn)備復(fù)雜的調(diào)用參數(shù)的過(guò)程。

　　4、還可以將文檔規(guī)范導(dǎo)入相關(guān)的工具里面（例如：Postman、SoapUI）、這些工具將會(huì)為我們自動(dòng)地創(chuàng)建自動(dòng)化測(cè)試。

三、怎么用

　　1、在項(xiàng)目pom.xml里面加入Swagger2相關(guān)的依賴

<!--swagger2配置-->
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.4.0</version>
    </dependency>
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.4.0</version>
    </dependency>
    <dependency>
      <groupId>com.github.xiaoymin</groupId>
      <artifactId>swagger-bootstrap-ui</artifactId>
      <version>1.6</version>
    </dependency>

　　2、新建Swagger2的配置類

package com.zhouhong.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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
 * @ClassName: Swagger2
 * @Description:
 * @Author: 周紅
 * @NickName: Tom-shuhu
 * @Date: Created in 2020/12/15
 **/
@Configuration
@EnableSwagger2
public class Swagger2 {
  //  http://localhost:8088/swagger-ui.html 原路徑
  //  http://localhost:8088/doc.html 原路徑
  //配置swagger2核心配置
  @Bean
  public Docket createRestApi(){
    return new Docket(DocumentationType.SWAGGER_2) //指定api類型位swagger2
      .apiInfo(apiInfo())            //用于定義api文檔匯總信息
        .select().apis(RequestHandlerSelectors
            .basePackage("com.zhouhong.controller")) //指定生成文檔的controller
        .paths(PathSelectors.any())　　　　　　
        .build();
  }
  private ApiInfo apiInfo(){
    return new ApiInfoBuilder()
        .title("Tom-shushu 的項(xiàng)目接口api") //文檔標(biāo)題
        .contact(new Contact("周紅", //作者
            "www.zhouhong.icu",　　
            "15249239025@163.com")) //聯(lián)系人
        .description("Tom-shushu 的項(xiàng)目api接口")//詳細(xì)信息
        .version("1.0.0")//文檔版本號(hào)
        .termsOfServiceUrl("www.zhouhong.icu")//網(wǎng)站地址
        .build();
  }
}

　　文檔配置說(shuō)明：

　　a.為任何接口生成API文檔，這種方式不必在接口方法上加任何注解，方便的同時(shí)也會(huì)因?yàn)闆](méi)有添加任何注解所以生成的API文檔也沒(méi)有注釋，可讀性不高。

@Bean
  public Docket createRestApi(){
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select()
        //為任何接口生成API文檔
        .apis(RequestHandlerSelectors.any())
        .paths(PathSelectors.any())
        .build();
  }

　　b.為當(dāng)前配置的包下controller生成API文檔

.apis(RequestHandlerSelectors.basePackage("com.troila"))

　　c.為有@Api注解的Controller生成API文檔

.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))

　　d.為有@ApiOperation注解的方法生成API文檔

.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))

三、常見(jiàn)注解簡(jiǎn)介

@Api：修飾整個(gè)類，描述Controller的作用
 @ApiOperation：描述一個(gè)類的一個(gè)方法，或者說(shuō)一個(gè)接口
 @ApiParam：?jiǎn)蝹€(gè)參數(shù)描述
 @ApiModel：用對(duì)象實(shí)體來(lái)作為入?yún)?
 @ApiProperty：用對(duì)象接實(shí)體收參數(shù)時(shí)，描述對(duì)象的一個(gè)字段
 @ApiResponse：HTTP響應(yīng)其中1個(gè)描述
 @ApiResponses：HTTP響應(yīng)整體描述
 @ApiIgnore：使用該注解忽略這個(gè)API
 @ApiError ：發(fā)生錯(cuò)誤返回的信息
 @ApiImplicitParam：一個(gè)請(qǐng)求參數(shù)
 @ApiImplicitParams： 多個(gè)請(qǐng)求參數(shù)