背景 在如今前後端分離的大背景下，前後端唯一打交道的就是API介面。前端只需要向後端請求url地址，後端只需將資料返回即可。前端工程師拿到的既是後端給到的一份完整的API文件，如果專案體量非常大的情況下，整理這些文件就需要浪費大量的時間。如果業務有變更的情況下，還需要再去更新文件，維護成本也是非常大。

今天介紹的主角就是Swagger線上生成API文件，極大的減少了人力的維護成本。可以線上直接在文件介面中測試。主要演示一下與Springboot整合的使用。Swagger支援多種語言的整合，詳細可以通過檢視其它資料。也支援文件的編寫, 文件編寫。

整合步驟

引入依賴檔案

<!--swagger2-->
 

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

編寫配置檔案

package cc.mrbird.common.swagger;

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;

/**
 * @Auther: jerry.feng
 * @Date: 2018/11/5
 * @Description: Swagger2 配置
 */

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //api文件掃描的包
                .apis(RequestHandlerSelectors.basePackage("cc.mrbird.system.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("CloudWallet API文件")
                .description("CloudWallet 雲錢包 RESTful介面文件")
                .termsOfServiceUrl("https://blog.csdn.net/fw19940314/article/list/")
                .version("1.0.1")
                .build();
    }
}

開啟Swagger 通過@EnableSwagger2 註解

@SpringBootApplication
@EnableTransactionManagement
@EnableCaching
@EnableSwagger2
@EnableAsync
public class Application {
    private static Logger log = LoggerFactory.getLogger(Application.class);
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
        log.info("FEBS started up successfully at {} {}", LocalDate.now(), LocalTime.now());
    }
}

API（Controller）層的編寫只截取了部分，一個是帶引數，一個是無引數

@RestController
public class DeptController {
    private Logger log = LoggerFactory.getLogger(this.getClass());
    @Autowired
    private DeptService deptService;

    @ApiOperation(value="獲取部門資訊", notes="獲取所有部門資訊")
    @RequestMapping(value = "dept/tree", method = RequestMethod.GET)
    @ResponseBody
    public ResponseBo getDeptTree() {
        try {
            Tree<Dept> tree = this.deptService.getDeptTree();
            return ResponseBo.ok(tree);
        } catch (Exception e) {
            log.error("獲取部門樹失敗", e);
            return ResponseBo.error("獲取部門樹失敗！");
        }
    }
    @ApiOperation(value="查詢部門資訊", notes="根據url的id來獲取部門詳細資訊")
    @ApiImplicitParam(name = "deptId", value = "部門ID", required = true, dataType = "Long")
    @RequestMapping(value = "dept/getDept", method = RequestMethod.GET)
    @ResponseBody
    public ResponseBo getDept(Long deptId) {
        try {
            Dept dept = this.deptService.findById(deptId);
            return ResponseBo.ok(dept);
        } catch (Exception e) {
            log.error("獲取部門資訊失敗", e);
            return ResponseBo.error("獲取部門資訊失敗，請聯絡網站管理員！");
        }
    }
}

註解的使用： swagger通過註解表明該介面會生成文件，包括介面名、請求方法、引數、返回資訊的等等。 @Api：修飾整個類，描述Controller的作用 @ApiOperation：描述一個類的一個方法，或者說一個介面 @ApiParam：單個引數描述 @ApiModel：用物件來接收引數 @ApiProperty：用物件接收引數時，描述物件的一個欄位 @ApiResponse：HTTP響應其中1個描述 @ApiResponses：HTTP響應整體描述 @ApiIgnore：使用該註解忽略這個API @ApiError ：發生錯誤返回的資訊 @ApiImplicitParam：一個請求引數 @ApiImplicitParams：多個請求引數

啟動專案，訪問http://localhost:8080/swagger-ui.html#/

這裡是使用在真實的專案中，介面有很多，剛才建立的RESTful風格的dept-controller。

線上測試，即可獲取介面資料。

這裡需要說一點的是可能專案中使用了許可權框架，會攔截Swagger請求的資源，例如我這裡使用的shiro安全框架。需要講Swagger這部分資源設定為免登陸認證。

//在shiroFilterFactoryBean，filterChainDefinitionMap過濾器中放行這幾個請求即可。
        filterChainDefinitionMap.put("/swagger-ui.html", "anon");
        filterChainDefinitionMap.put("/webjars/**", "anon");
        filterChainDefinitionMap.put("/v2/**", "anon");
        filterChainDefinitionMap.put("/swagger-resources/**", "anon");

到這裡基本的開發API文件就生成成功

參考文章：https://blog.csdn.net/saytime/article/details/74937664