SpringBoot學習（六）--SpringBoot集成swagger在線API文檔工具

版權聲明：作者原創，轉載請註明出處。
本系列文章目錄地址：http://blog.csdn.net/u011961421/article/details/79416510

簡介

Swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目標是使客戶端和文件系統作爲服務器以同樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，允許API來始終保持同步。 Swagger 讓部署管理和使用功能強大的API從未如此簡單。

實戰

直接正題，SpringBoot集成Swagger同樣簡潔明瞭，下面開始介紹集成過程以及簡單運用，而關於Swagger的深層介紹這裏不作擴展。

1.pom.xml加入Swagger依賴包

<!-- http://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.5.0</version>
</dependency>

<!-- http://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.5.0</version>
</dependency>

swagger-ui是swagger的子模塊，提供了統一的API展示頁面，同樣swagger還有其他模塊，如Swagger Editor,Swagger CodeGen等，對於一般運用swagger-ui已經足夠。

2.編寫config配置類
直接貼demo，如下：

@EnableSwagger2
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("demo")
                .genericModelSubstitutes(DeferredResult.class)
                .useDefaultResponseMessages(false)
                .forCodeGeneration(false)
                .pathMapping("/")
                .select()
                .paths(PathSelectors.any())
                .build()
                .apiInfo(demoApiInfo());
    }

    private ApiInfo demoApiInfo() {
        ApiInfo apiInfo = new ApiInfo(
                "SPRING BOOT AND SWAGGER TEST API",//大標題
                "Test REST API, all the applications could access the Object model data via JSON.",//小標題
                "1.0",//版本
                "NO terms of service",//服務條款
                new Contact("test","66666","雙擊關注"),//作者
                "Spring Boot Demo",//鏈接顯示文字
                "http://localhost:8080/demo/getAll"//網站鏈接
        );
        return apiInfo;
    }
}

3.添加swagger註解
由於swagger是侵入式的，但好在只需要添加相關注解，無需改動其他代碼，所以即使是舊工程新引入swagger的改動也是可以接受的，例在前面學習的demo中引入swagger如下：

@Controller
@RequestMapping(value = "/demo", method = RequestMethod.GET)
@Api(description = "swagger測試接口DemoController",tags = {"DemoController"})
public class DemoController {
    private static final Logger log = LoggerFactory.getLogger(DemoController.class);

    @Autowired
    DemoService demoService;

    @Autowired
    RedisManager redisManager;

    @Value("${spring.profiles.active}")
    private String profileActive;

    @ApiOperation(value = "獲取所有信息接口" , notes = "swagger測試接口")
    @RequestMapping(value = "/getAll")
    public String testDemo(Map<String, Object> map) {
        System.out.println("入參key爲:"+map.toString());
        List<Demo> demos = demoService.getDemos();
        map.put("data", demos);
        System.out.println(demos.toString());
        System.out.println(profileActive);
        log.debug("debug---log-------------" + demos.toString());
        log.info("info---log-------------" + demos.toString());
        log.warn("warn---log-------------" + demos.toString());
        log.error("error---log-------------" + demos.toString());
        return ("/testDemo");
    }

    @ApiOperation(value = "redis測試" , notes = "redis測試接口")
    @RequestMapping(value = "/testRedis", method = RequestMethod.GET)
    @ResponseBody
    public String testRedis(@RequestParam String key) {
        System.out.println("入參key爲:"+key);
        if(StringUtils.isEmpty(key)) {
            return "入參爲空";
        }
        String s = "查詢結果爲:"+redisManager.getStr(key);
        return s;
    }
}

常用註解有如下幾個：
- @Api()用於類；
表示標識這個類是swagger的資源
- @ApiOperation()用於方法；
表示一個http請求的操作
- @ApiParam()用於方法，參數，字段說明；
表示對參數的添加元數據（說明或是否必填等）
- @ApiModel()用於類
表示對類進行說明，用於參數用實體類接收
- @ApiModelProperty()用於方法，字段
表示對model屬性的說明或者數據操作更改
- @ApiIgnore()用於類，方法，方法參數
表示這個方法或者類被忽略
- @ApiImplicitParam() 用於方法
表示單獨的請求參數
- @ApiImplicitParams() 用於方法，包含多個 @ApiImplicitParam

關於更詳細的註解使用，在網上找了個不錯的介紹以供參考https://www.jianshu.com/p/12f4394462d5

4.啓動工程，訪問工程路徑加/swagger-ui.html，本文例子路徑爲http://localhost:8080/swagger-ui.html，這裏需要注意的是有訪問控制的，記得放開swagger的相關訪問控制，否則訪問不到相關資源。
訪問後頁面如下，展示根據配置的掃描路徑的所有controller，沒有添加加任何註解會以默認值顯示。

單擊controller可顯示當前controller下所有方法，單擊方法名可以顯示所以信息如下，該頁面提供了測試功能，是前後端分離的最主要功能。parameters展示了所以入參，在value填入參數值後，點擊”Try it out!”便可發起請求，得到並展示請求相關的所有信息。

最後，SpringBoot集成swagger到這已經集成完成，SpringBoot整個學習系列案例、以及本文案例地址爲https://github.com/15651037763/cms，關於swagger使用的更多細節並未深入介紹，並且博主也僅停留在一般運用上，如有疑問，歡迎留言評論。