Swagger+SpringBoot整理

maven依賴

 1 <dependency>
 2     <groupId>io.springfox</groupId>
 3     <artifactId>springfox-swagger2</artifactId>
 4     <version>2.2.2</version>
 5 </dependency>
 6 <dependency>
 7     <groupId>io.springfox</groupId>
 8     <artifactId>springfox-swagger-ui</artifactId>
 9     <version>2.2.2</version>
10 </dependency>

SWAGGERCONFIG

 1 @Configuration  2 @EnableSwagger2  3 public class Swagger2 {  4 
 5  @Bean  6     public Docket createRestApi() {  7         return new Docket(DocumentationType.SWAGGER_2)  8  .apiInfo(apiInfo())  9  .select() 10                 .apis(RequestHandlerSelectors.basePackage("com.didispace.web"))//掃描包
　　　　　　　　　　　　//.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //被註解的方法 11  .paths(PathSelectors.any()) 12  .build(); 13  } 14 
15     private ApiInfo apiInfo() { 16         return new ApiI標題") 18                 .description("---一個說明-----") 19                 .termsOfServiceUrl("http://blog.didispace.com/") 20                 .contact("程序猿") 21                 .version("1.0") 22  .build(); 23  } 24 
25 }

Controller中使用

 

 1 package com.qzt360.controller;  2 
 3 import io.swagger.annotations.*;  4 import org.springframework.web.bind.annotation.RequestMapping;  5 import org.springframework.web.bind.annotation.RequestMethod;  6 import org.springframework.web.bind.annotation.RestController;  7 
 8 @Api(tags = "接口描述")  9 @ApiResponses(value = { @ApiResponse(code = 200, message = "Successful — 請求已完成"), 10         @ApiResponse(code = 400, message = "請求中有語法問題，或不能知足請求"), 11         @ApiResponse(code = 401, message = "未受權客戶機訪問數據"), 12         @ApiResponse(code = 404, message = "服務器找不到給定的資源；文檔不存在"), 13         @ApiResponse(code = 500, message = "服務器不能完成請求") }) 14 @RestController 15 @RequestMapping("/t") 16 public class TestController { 17     //限定請求方式一
18     @ApiOperation(value = "用途、做用", notes = "說明", httpMethod = "GET") 19     // 參數方式一
20  @ApiImplicitParams({ 21             @ApiImplicitParam(name = "str", value = "用戶標識", required = true, paramType = "query", dataType = "String") }) 22     @RequestMapping("t01") 23     public String testSw(String str) { 24         return "zshiygcshi" + str; 25  } 26 
27     @ApiOperation(value = "cshi", notes = "新增註冊") 28  @ApiImplicitParams({ 29             @ApiImplicitParam(name = "str", value = "參數的漢字說明、解釋", required = true, paramType = "query", dataType = "String") }) 30     //限定請求方式二
31     @RequestMapping(value = "t02", method = { RequestMethod.GET, RequestMethod.POST }) 32     public String testSw02(String str) { 33         return "zshiygcshi" + str; 34  } 35 
36     @ApiOperation(value = "cshi", notes = "新增註冊", httpMethod = "POST") 37     @RequestMapping("t03") 38     // 參數方式二
39     public String testSw03(@ApiParam(name = "測試", value = "cd") String str) { 40         return "zshiygcshi" + str; 41  } 42 }

 

完成上述代碼添加上，啓動Spring Boot程序，訪問：http://localhost:8080/swagger-ui.html

效果圖

 

線上環境在配置類中加

 

.paths(PathSelectors.none())//若是是線上環境，添加路徑過濾，設置爲所有都不符合

 

主要註解說明:

Swagger2 基本使用：

• @Api 描述類/接口的主要用途
• @ApiOperation 描述方法用途
• @ApiImplicitParam 描述方法的參數
• @ApiImplicitParams 描述方法的參數(Multi-Params)
• @ApiIgnore 忽略某類/方法/參數的文檔

1. @Api：用在請求的類上，說明該類的做用

@Api：用在請求的類上，說明該類的做用 tags="說明該類的做用"
    value="該參數沒什麼意義，因此不須要配置
 示例： @Api(tags="APP用戶註冊Controller")

 

二、@ApiOperation：用在請求的方法上，說明方法的做用

@ApiOperation："用在請求的方法上，說明方法的做用" value="說明方法的做用" notes="方法的備註說明"

示例：

@ApiOperation(value="用戶註冊",notes="手機號、密碼都是必輸項，年齡隨邊填，但必須是數字")

三、@ApiImplicitParams：用在請求的方法上，包含一組參數說明

 1 @ApiImplicitParams：用在請求的方法上，包含一組參數說明  2  @ApiImplicitParam：用在 @ApiImplicitParams 註解中，指定一個請求參數的配置信息  3  name：參數名  4  value：參數的漢字說明、解釋  5  required：參數是否必須傳  6  paramType：參數放在哪一個地方  7             · header --> 請求參數的獲取：@RequestHeader  8             · query --> 請求參數的獲取：@RequestParam  9             · path（用於restful接口）--> 請求參數的獲取：@PathVariable 10  · body（不經常使用） 11  · form（不經常使用） 12         dataType：參數類型，默認String，其它值dataType="Integer"       
13  defaultValue：參數的默認值 14 
15 示列： 16 
17 @ApiImplicitParams({ 18     @ApiImplicitParam(name="mobile",value="手機號",required=true,paramType="form"), 19     @ApiImplicitParam(name="password",value="密碼",required=true,paramType="form"), 20     @ApiImplicitParam(name="age",value="年齡",required=true,paramType="form",dataType="Integer") 21 })

四、@ApiResponses：用於請求的方法上，表示一組響應

@ApiResponses：用於請求的方法上，表示一組響應 @ApiResponse：用在@ApiResponses中，通常用於表達一個錯誤的響應信息 code：數字，例如400 message：信息，例如"請求參數沒填好" response：拋出異常的類

示例：

@ApiOperation(value = "select1請求",notes = "多個參數，多種的查詢參數類型") @ApiResponses({ @ApiResponse(code=400,message="請求參數沒填好"), @ApiResponse(code=404,message="請求路徑沒有或頁面跳轉路徑不對") })

五、@ApiModel：用於響應類上，表示一個返回響應數據的信息

@ApiModel：用於響應類上，表示一個返回響應數據的信息 （這種通常用在post建立的時候，使用@RequestBody這樣的場景， 請求參數沒法使用@ApiImplicitParam註解進行描述的時候） @ApiModelProperty：用在屬性上，描述響應類的屬性

遇到問題:

Spring Boot 配置靜態資源處理

• 先講幾點有關嵌入式 Tomcat 運行的事項
  
  • request.getSession().getServletContext().getRealPath(「/」)，這個不用多說了，總之很重要，先將其簡稱爲 docBase，即 「文檔根目錄」
  • 當項目中不存在 src/main/webapp 目錄時，docBase 爲C盤臨時目錄，例如 C:\Users\Administrator\AppData\Local\Temp\tomcat-docbase.2872246570823772896.8080\
  • 當項目中存在 src/main/webapp 目錄時
    
    • 若是該目錄存在於 Maven 項目父模塊中，則 docBase 爲父模塊的 src/main/webapp
    • 若是 Maven 項目父模塊缺乏該目錄，此時，即便子模塊存在 src/main/webapp 目錄，也視爲不見，docBase 爲C盤臨時目錄

綜上，若是咱們想要經過 「文檔根目錄」 來定位到某些資源的話，首先要保證存在 src/main/webapp 目錄，不然，建議直接定位到 classpath 下的資源（即 src/main/resource 目錄下的資源），具體配置以下

1.不存在 @EnableWebMVC

• Spring Boot 的 @EnableAutoConfiguration 會觸發自動配置類 WebMvcAutoConfiguration，該類配置了一些默認的靜態資源映射
  
  • 自動映射 localhost:8080/** 爲
    
    • classpath:/resources/
    • classpath:/static/
    • classpath:/public/
    • classpath:/META-INF/resources/
  • 自動映射 localhost:8080/webjars/** 爲
    
    • classpath:/META-INF/resources/webjars/

此時，咱們不須要多做些什麼，只須要將靜態資源放入 src/main/resources 目錄下的 resources、static 或 public 文件夾下，可直接經過 url 定位相關資源，例如 localhost:8080/index.html 定位到 src/main/resources/static/index.html

可是，若是使用瞭如下的自定義配置，則以上默認配置通通無效

@Configuration public class GoWebMvcConfigurerAdapter extends WebMvcConfigurerAdapter { @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { //配置靜態資源處理
        registry.addResourceHandler("/**") .addResourceLocations("classpath:/resources2/") .addResourceLocations("classpath:/static2/") .addResourceLocations("classpath:/public2/") .addResourceLocations("classpath:/META-INF/resources2/"); } }

 

---

2.若是存在 @EnableWebMVC

若是使用了 @EnableWebMvc，那麼自動配置類 WebMvcAutoConfiguration 會失效，所以官方默認的 /static, /public, META-INF/resources, /resources 都不復存在

這種狀況下，咱們只能手動添加如下配置，切記，若是不添加 classpath 前綴，

則定位到 「文檔根目錄」（通常是 src/main/webapp 目錄）下的資源，此時，咱們能夠將靜態資源放入 src/main/webapp 目錄下的 resources、static 或 public 文件夾下

，而後經過 url 直接定位相關資源，例如 localhost:8080/index.html 定位到 src/main/webapp/static/index.html

 1 @Configuration  2 public class GoWebMvcConfigurerAdapter extends WebMvcConfigurerAdapter {  3 
 4  @Override  5     public void addResourceHandlers(ResourceHandlerRegistry registry) {  6         //配置靜態資源處理
 7         registry.addResourceHandler("/**")  8                 .addResourceLocations("resources/")  9                 .addResourceLocations("static/") 10                 .addResourceLocations("public/") 11                 .addResourceLocations("META-INF/resources/"); 12     }