最近專案與前端對接時開始接觸Swagger。

Swagger：一個規範和完整的框架，用於生成、描述、呼叫和視覺化 RESTful 風格的 Web 服務。總體目標是使客戶端和檔案系統作為伺服器以同樣的速度來更新。檔案的方法，引數和模型緊密整合到伺服器端的程式碼，允許API來始終保持同步。

用法：

一、新增依賴包

<!--pom.xml檔案-->
        <!--swagger2-->
        <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>
 

二、新增配置類 ：Swagger2Config

package com.cdqyzj.admin.system.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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/*
 * Swagger2配置類
 * 在與spring boot整合時，放在與Application.java同級的目錄下。
 * 通過@Configuration註解，讓Spring來載入該類配置。
 * 再通過@EnableSwagger2註解來啟用Swagger2。
 */
@EnableSwagger2
@Configuration
public class Swagger2Config {
    /**
     * 建立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.swaggerTest.controller"))
                //為當前包路徑
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 建立該API的基本資訊（這些基本資訊會展現在文件頁面中）
     * 訪問地址：http://專案實際地址/swagger-ui.html
     * @return
     */
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
        		//頁面標題
                .title("Spring Boot中使用Swagger2構建RESTful APIs")
                //
                // .termsOfServiceUrl("http://www.baidu.com")
                //建立人
                .contact("我啥時候寫了這玩意兒啊？9月29日我都還不知道Swagger2是個啥玩意兒")
                //版本號
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
}
 

三、在介面處添加註解

//附加稅
@Controller
@RequestMapping("/addTax")
@Api(value = "AddtaxController|一個關於附加稅的控制器")
public class AddtaxController {

	public final String prefix = "WeChat_Files/backstage_Files/manage_AddTax";
	
	@Autowired
	private AddtaxService addtaxService;
	@Autowired
	private UCompanyService ucomService;

	...
    
	@ResponseBody
	@RequestMapping(value="/list_user/{userId}/{year}/{taxType}",method=RequestMethod.GET)
	@ApiOperation(value="根據使用者ID、具體年份和稅務型別獲取具體附加稅資訊", notes="test: 稅務型別包括：季報 月報")
        @ApiImplicitParams({
            @ApiImplicitParam(paramType="query", name = "userId", value = "使用者ID", required = true, dataType = "Integer"),
            @ApiImplicitParam(paramType="query", name = "year", value = "稅務時間", required = true, dataType = "String"),
            @ApiImplicitParam(paramType="query", name = "taxType", value = "稅務型別", required = true, dataType = "String")
        })
	public PageUtil list_user(@PathVariable("userId")int userId,@PathVariable("year")int year,@PathVariable("taxType")String taxType){
		System.err.println("按使用者查全部:userId:"+userId+"\tyear:"+year+"\t taxType:"+taxType);
		List<Addtax> rows;
		PageUtil page = new PageUtil();
		...
           具體解決方法
        ...
		page.setRows(rows);
		page.setTotal(total);
		return page;
	}
	
 

五、Swagger使用的註解及其說明

@Api：用在類上，說明該類的作用。

@ApiOperation：註解來給API增加方法說明。

@ApiImplicitParams : 用在方法上包含一組引數說明。

@ApiImplicitParam：用來註解來給方法入參增加說明。

@ApiResponses：用於表示一組響應

@ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應資訊

    l   code：數字，例如400

    l   message：資訊，例如"請求引數沒填好"

    l   response：丟擲異常的類   

@ApiModel：描述一個Model的資訊（一般用在請求引數無法使用@ApiImplicitParam註解進行描述的時候）

    l   @ApiModelProperty：描述一個model的屬性