本文目錄
一、Swagger前言
1、是一款讓你更好的書寫API文檔的規範且完整框架。
2、用於提供描述、生產、消費和可視化的RESTful Web Service。
3、是由龐大工具集合支撐的形式化規範。
Swagger是一個規範和完整的框架，用於生成、描述、調用和可視化RESTful風格的Web服務。這個集合涵蓋了從終端用戶接口、底層代碼庫到商業API管理的方方面面。
Swagger的作用：
1、接口的文檔在線自動生成。
2、功能測試。
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資源聲明以各種語言生成客戶端代碼。
二、使用方法
方法1：使用第三方的依賴
（懶人的方法，只需2步）（這是一個依賴集合，添加一個即可引入Swagger所使用的全部依賴）
步驟1、在pom.xml文件中添加第三方swagger依賴
<!-- https://mvnrepository.com/artifact/com.spring4all/swagger-spring-boot-starter -->
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.9.0.RELEASE</version>
</dependency>
步驟2、在Spring Boot項目的啓動類上添加@EnableSwagger2Doc註解，就可以直接使用了。
拓展：
拓展1：查看swagger最新的maven倉庫依賴：https://mvnrepository.com/artifact/com.spring4all/swagger-spring-boot-starter
拓展2：GitHub上swagger依賴實現的項目：https://github.com/SpringForAll/spring-boot-starter-swagger 這裏面有詳細的講解。
Swagger-ui界面如下所示：訪問http://localhost:8080/swagger-ui.html
方法2：使用官方依賴
步驟1、在pom.xml文件中添加swagger相關依賴
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
第一個是API獲取的包，第二是官方給出的一個ui界面。這個界面可以自定義，默認是官方的，對於安全問題，以及ui路由設置需要着重思考。
步驟2、swagger的configuration
需要特別注意的是swagger scan base package，這是掃描註解的配置，即你的API接口位置。
package com.baidu.practice.config.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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean(value = "restApi")
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("天氣類接口文檔")
.apiInfo(apiInfo())
.useDefaultResponseMessages(true)
.select()
.apis(RequestHandlerSelectors.basePackage("com.baidu.practice.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("天氣類接口")
.description("各種類型的天氣類接口彙總")
.termsOfServiceUrl("")
.version("2.0")
.build();
}
@Bean
public Docket smallHost(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("新聞類接口文檔")
.useDefaultResponseMessages(true)
.apiInfo(smallHostApiInfo())
.forCodeGeneration(false)
.select()
.paths(PathSelectors.any())
.apis(RequestHandlerSelectors.basePackage("com.baidu.practice.newscontroller"))
.build();
}
private ApiInfo smallHostApiInfo(){
return new ApiInfoBuilder()
.title("新聞類接口")
.description("各種類型的新聞類接口彙總")
.version("3.0")
.build();
}
}
方法2同樣可以達到方法1的效果，同樣訪問 http://localhost:8080/swagger-ui.html 這個路徑，可以得到Swagger-ui界面，如上圖所示
三、swagger常用的API
敬請期待ing.........
【參考資料】
1、SpringForAll/spring-boot-starter-swagger：https://github.com/SpringForAll/spring-boot-starter-swagger