spring boot集成Swagger2

第一步：jar包的引入

這里我的springboot 和framework都是1.5.9

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

 

第二步：swagger的配置啟動類

有人說這個類必須放到啟動類同級，無稽之談，掃描包的配置基礎去補補。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
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;

/**
 * 自動文檔注解
 * 訪問地址：注意端口后面+上context-path
 * springboot中的swagger：http://localhost:8080/swagger-ui.html
 * druid數據庫監控　：http://localhost:8080/druid/index.html
 */
@Configuration
public class SwaggerConfig extends WebMvcConfigurerAdapter {

   @Bean
   public Docket businessDocket() {
      return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select() // 為當前包路徑
            .apis(RequestHandlerSelectors
             .basePackage("com.sanyi.qibaobusiness.core.controller.busniess"))
            .paths(PathSelectors.any())
            .build();
   }

   // 構建 api文檔的詳細信息函數
   private ApiInfo apiInfo() {
      return new ApiInfoBuilder() // 頁面標題
            .title("三易業務端繪圖端 API")
            .termsOfServiceUrl("http://localhost:8080/swagger-ui.html")
            .contact("lanhaifeng") // 創建人
            .version("1.0") // 版本號           
            .description("訪問 http://localhost:8080/swagger-ui.html")//描述
            .build();
   }

   /**
    * 我們在訪問http://localhost/swagger-ui.html時，這個swagger-ui.html相關的所有前端靜態文件都在springfox-swagger-ui-2.2.2.jar里面。
    * SpringBoot自動配置本身並不會把/swagger-ui.html這個路徑映射到對應的目錄META-INF/resources/下面。我們加上這個映射即可
    * 這個也是發生404的解決方案
    * @param registry
    */
   @Override
   public void addResourceHandlers(ResourceHandlerRegistry registry) {
      registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
      registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
      registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
   }

}

 

三、在啟動類加上@EnableSwagger2注解。

import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.builder.SpringApplicationBuilder;
import org.springframework.boot.web.servlet.ServletComponentScan;
import org.springframework.boot.web.support.SpringBootServletInitializer;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


@EnableSwagger2
@SpringBootApplication
//@EnableConfigurationProperties({YmlConfig.class})//不需要了.因為YmlConfig類上有@Component注解
@MapperScan("com.sanyi.qibaobusiness.core.mapper") //配置掃描mapper接口的地址
public class QibaobusinessApplication extends SpringBootServletInitializer {


   public static void main(String[] args) {
      SpringApplication.run(QibaobusinessApplication.class, args);
   }

   @Override
   protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
      return application.sources(QibaobusinessApplication.class);
   }
}

 

四、在controller中添加注解

這些注解看實際使用情況自行添加。

@Api：用在類上，說明該類的作用
 
@ApiOperation：用在方法上，說明方法的作用，標注在具體請求上，value和notes的作用差不多，都是對請求進行說明；tags則是對請求進行分類的，比如你有好幾個controller，分別屬於不同的功能模塊，那這里我們就可以使用tags來區分了。
 
@ApiImplicitParams：用在方法上包含一組參數說明
 
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個請求參數的各個方面。
 
@ApiResponses：用於表示一組響應
 
@ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應信息
 
@ApiModel：描述一個Model的信息（這種一般用在post創建的時候，使用@RequestBody這樣的場景，請求參數無法使用@ApiImplicitParam注解進行描述的時候）表明這是一個被swagger框架管理的model，用於class上
@ApiModelProperty： 這里顧名思義，描述一個model的屬性，就是標注在被標注了@ApiModel的class的屬性上，這里的value是對字段的描述，example是取值例子，注意這里的example很有用，
對於前后端開發工程師理解文檔起到了關鍵的作用，因為會在api文檔頁面上顯示出這些取值來；這個注解還有一些字段取值，可以自己研究，舉例說一個：position，表明字段在model中的順序。

 

下面羅列下實際開發中最常用的三種寫法，注意請求方法必須寫。這三種基本夠用了。httpMethod這個參數必須設置。

//注解在類上,其實只有這個value值有效
@Api(value="/decorate[裝修選型版塊Controller]", tags="裝修選型版塊Controller")

//注解在方法上,注意這個httpMethod必須要寫，不然各種請求都會幫你羅列出來
//paramType = "path"這個參數，如果不是請求方法后面直接帶參數可以去掉，例如/getUserId/2,這種請求這個參數就需要配置，否則應該去除
@ApiOperation(value="獲取用戶詳細信息", notes="根據url的id來獲取用戶詳細信息",httpMethod = "GET")//如果沒有請求參數，用這個一個就行
@ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Integer", paramType = "path")

//多個請求參數，注意這里就沒有 paramType = "path"。
@ApiOperation(value="合作方式", notes="選擇合作方式",httpMethod = "POST")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "machinePrcie", value = "購買機械價格", required = true, dataType = "Double"),
            @ApiImplicitParam(name = "daystate", value = "按天計算折扣", required = true, dataType = "Double"),
            @ApiImplicitParam(name = "overserPrice", value = "按天計算價格", required = true, dataType = "Double"),
            @ApiImplicitParam(name = "areastate", value = "按面積計算折扣", required = true, dataType = "Double"),
            @ApiImplicitParam(name = "prcie", value = "按面積計算總價", required = true, dataType = "Double")
    })

 

四、安全驗證放過swagger相關

實際上線則不能放過，或者相關文檔刪除，相關接口必須對外保密。

/*swagger*/
        filterChainDefinitionMap.put("/swagger-ui.html", "anon");
        filterChainDefinitionMap.put("/swagger-resources/**", "anon");
        filterChainDefinitionMap.put("/v2/**", "anon");
        filterChainDefinitionMap.put("/webjars/**", "anon");

 

五、訪問：http://localhost:8080/swagger-ui.html

當出現：fetching resource list: http://localhost:8080/v2/api-docs 時稍微等待一兩分鍾，之后文檔會自動加載出來