Swagger2整合SpringBoot

Swagger2整合SpringBoot

Swagger2註解詳細

@Api：用在請求的類上，表示對類的說明
    tags="說明該類的做用，能夠在UI界面上看到的註解"
    value="該參數沒什麼意義，在UI界面上也看到，因此不須要配置"

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

@ApiImplicitParams：用在請求的方法上，表示一組參數說明
    @ApiImplicitParam：用在@ApiImplicitParams註解中，指定一個請求參數的各個方面
        name：參數名
        value：參數的漢字說明、解釋
        required：參數是否必須傳
        paramType：參數放在哪一個地方
            · header --> 請求參數的獲取：@RequestHeader
            · query --> 請求參數的獲取：@RequestParam
            · path（用於restful接口）--> 請求參數的獲取：@PathVariable
            · body（不經常使用）
            · form（不經常使用）    
        dataType：參數類型，默認String，其它值dataType="Integer"       
        defaultValue：參數的默認值

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

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

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

@Api：用在請求的類上，說明該類的做用
    tags="說明該類的做用"
    value="該參數沒什麼意義，因此不須要配置"
複製代碼

示例

@Api(tags="APP用戶註冊Controller")

2. @ApiOperation：用在請求的方法上，說明方法的做用

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

示例

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

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

@ApiImplicitParams：用在請求的方法上，包含一組參數說明
    @ApiImplicitParam：用在 @ApiImplicitParams 註解中，指定一個請求參數的配置信息       
        name：參數名
        value：參數的漢字說明、解釋
        required：參數是否必須傳
        paramType：參數放在哪一個地方
            · header --> 請求參數的獲取：@RequestHeader
            · query --> 請求參數的獲取：@RequestParam
            · path（用於restful接口）--> 請求參數的獲取：@PathVariable
            · body（不經常使用）
            · form（不經常使用）    
        dataType：參數類型，默認String，其它值dataType="Integer"       
        defaultValue：參數的默認值
複製代碼

示例

@ApiImplicitParams({
    @ApiImplicitParam(name="mobile",value="手機號",required=true,paramType="form"),
    @ApiImplicitParam(name="password",value="密碼",required=true,paramType="form"),
    @ApiImplicitParam(name="age",value="年齡",required=true,paramType="form",dataType="Integer")
})
複製代碼

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：用在屬性上，描述響應類的屬性
複製代碼

示例

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

import java.io.Serializable;

@ApiModel(description= "返回響應數據")
public class RestMessage implements Serializable{

    @ApiModelProperty(value = "是否成功")
    private boolean success=true;
    @ApiModelProperty(value = "返回對象")
    private Object data;
    @ApiModelProperty(value = "錯誤編號")
    private Integer errCode;
    @ApiModelProperty(value = "錯誤信息")
    private String message;

    /* getter/setter */
}
複製代碼

具體案例

組件說明

Swagger是一組開源項目，其中主要要項目以下：

1. Swagger-tools: 提供各類與Swagger進行集成和交互的工具。例如模式檢驗、Swagger 1.2文檔轉換成Swagger 2.0文檔等功能。
2. Swagger-core: 用於Java/Scala的的Swagger實現。與JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架進行集成。
3. Swagger-js: 用於JavaScript的Swagger實現。
4. Swagger-node-express: Swagger模塊，用於node.js的Express web應用框架。
5. Swagger-ui：一個無依賴的HTML、JS和CSS集合，能夠爲Swagger兼容API動態生成優雅文檔。
6. Swagger-codegen：一個模板驅動引擎，經過分析用戶Swagger資源聲明以各類語言生成客戶端代碼。

POM引用

版本過高可能會報異常信息

<dependencies>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.6.1</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.6.1</version>
		</dependency>
	</dependencies>
複製代碼

配置Swagger2Config

說明：該類跟Application同目錄

/** * @Auther: zhangbh * @Date: 2019/10/8 09:41 * @Description: Swagger2配置類 * 在與SpringBoot集成時，放在與Application同級的目錄下 * 經過@Configuration註解，讓Spring來加載該類配置 * 再經過@EnableSwagger2註解來啓用Swagger2 */
@Configuration
@EnableSwagger2
public class Swagger2 {
    /** * 建立API應用apiInfo（）增長API相關信息 * 經過select（）函數返回一個ApiSelectorBuilder實例，用來控制哪些接口暴露給Swagger來展示 * 採用指定掃描的包路徑來定義指定要創建API的目錄 * @return */
    @Bean
    public Docket createRestApi() {
        return new Docket((DocumentationType.SWAGGER_2))
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.glodon"))
                .paths(PathSelectors.any())
                .build();
    }
    /** * 建立該API的基本信息（這些基本信息會展示在文檔頁面） * 訪問地址：http://項目實際地址/swagger-ui.html * @return */
    private ApiInfo apiInfo() {
        //配置界面說明
        return new ApiInfoBuilder()
                //頁面標題
                .title("gzzjz-zjfx接口文檔")
                //描述
                .description("廣州造價站-造價子系統接口文檔")
                //建立人
                .contact("zhangbh")
                .version("1.0")
                .build();
    }
}
複製代碼

若是不指定Http類型，默認是7中類型都支持

Conntroller中定義的方法必須在@RequestMapper中顯示的指定RequestMethod類型，不然SawggerUi會默認爲全類型皆可訪問， API列表中會生成多條項目。

綜合應用

Controller

@RestController
@RequestMapping("/user")
@Api(tsgs = {"UserController"}, description = "用戶接口")
public class UserController {
	
	@PostMapping("/findUser")
	@ApiOperation(value="查詢用戶信息", notes="根據用戶名，年齡等信息查詢用戶信息列表")
	@ApiImplicitParams({
		@ApiImplicitParam(paramType="query", name = "id", value = "請求標識", required = true, dataType = "String"),
	})
	@ApiResponses({
		@ApiResponse(code=201,message="成功1",response = UserVo.class),
		@ApiResponse(code=400,message="失敗",response = UserVo.class)
	})
	public List<UserVo> findUser(@RequestParam String id, @RequestBody UserBo userBo){
		System.out.println(id);
		System.out.println(userBo.toString());
		
		List<UserVo> list = new ArrayList<UserVo>();
		
		UserVo e = new UserVo();
		e.setAge("age1");
		e.setUserName("userName1");
		e.setUserBo(userBo);
		list.add(e );
		
		UserVo e2 = new UserVo();
		e2.setUserBo(userBo);
		e2.setAge("age2");
		e2.setUserName("userName2");
		list.add(e2 );
		
		return list;
	}
}
複製代碼

Entity

@ApiModel(value = "用戶BO")
public class UserBo {
    @ApiModelProperty(value="用戶名" ,required=true)
	 private String userName;
    @ApiModelProperty(value="年齡" ,required=true)
	 private String age;
    // 省略getter & setter方法
}
複製代碼

API

注意

除了在攔截器中對Swagger路徑放行以外

public void addInterceptors(InterceptorRegistry registry) {
    	registry.addInterceptor(logInterceptor).addPathPatterns("/**")
    	    .excludePathPatterns("/api1/heartbeat")
            .excludePathPatterns("/v2/api-docs")
            .excludePathPatterns("/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**");
複製代碼

可能後臺會報錯

No mapping found for HTTP request with URI [/swagger-resources/configuration/ui] in DispatcherServlet with name 'dispatcherServlet'
複製代碼

解決方案

這個錯誤，是由於資源映射問題致使。 咱們在訪問http://127.0.0.1:8188/swagger-ui.html 時，這個swagger-ui.html相關的全部前端靜態文件都在springfox-swagger-ui-2.6.1.jar裏面。目錄以下：

Spring Boot自動配置自己不會自動把/swagger-ui.html這個路徑映射到對應的目錄META-INF/resources/下面。咱們加上這個映射便可。代碼以下：

public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

複製代碼

Swagger解析

首頁/swagger-ui.html

地址：http://localhost:8080/swagger-ui.html

首頁信息接口/v2/api-docs

地址：http://localhost:8080/v2/api-docs

參考

blog.csdn.net/sanyaoxu_2/…