Swagger+SpringBoot整理

weixin_30488085發表於2020-04-06
SwaggerSpring Boot

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")

 

2、@ApiOperation：用在請求的方法上，說明方法的作用

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

示例：

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

3、@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 })

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

@ApiResponses：用於請求的方法上，表示一組響應
    @ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應資訊
        code：數字，例如400
        message：資訊，例如"請求引數沒填好"
        response：丟擲異常的類

示例：

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

5、@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     }

轉載於:https://www.cnblogs.com/sylwh/p/9338670.html

相關文章