一：Swagger is what？
1、是一款讓你更好的書寫API文檔的規範且完整框架。
2、提供描述、生產、消費和可視化RESTful Web Service。
3、是由龐大工具集ruhe合支撐的形式化規範。這個集合涵蓋了從終端用戶接口、底層代碼庫到商業API管理的方方面面。
二：如何使用Swagger？
1.與SpringBoot項目集成 =====>
在pom.xml文件中添加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>
儘量下載高的版本號，不然會出現下面類類似情況：
***************************
APPLICATION FAILED TO START
***************************
Description:
Parameter 0 of method linkDiscoverers in org.springframework.hateoas.config.HateoasConfiguration required a single bean, but 15 were found:
- modelBuilderPluginRegistry: defined in null
- modelPropertyBuilderPluginRegistry: defined in null
- typeNameProviderPluginRegistry: defined in null
- documentationPluginRegistry: defined in null
- apiListingBuilderPluginRegistry: defined in null
- operationBuilderPluginRegistry: defined in null
- parameterBuilderPluginRegistry: defined in null
- expandedParameterBuilderPluginRegistry: defined in null
- resourceGroupingStrategyRegistry: defined in null
- operationModelsProviderPluginRegistry: defined in null
- defaultsProviderPluginRegistry: defined in null
- pathDecoratorRegistry: defined in null
- relProviderPluginRegistry: defined by method 'relProviderPluginRegistry' in class path resource [org/springframework/hateoas/config/HateoasConfiguration.class]
- linkDiscovererRegistry: defined in null
- entityLinksPluginRegistry: defined by method 'entityLinksPluginRegistry' in class path resource [org/springframework/hateoas/config/WebMvcEntityLinksConfiguration.class]
2.配置Swagger （也就是創建個類Swagger2 + 註解 就完事了）
@Configuration //等價於 @Component
@EnableSwagger2 //開啓swagger2
public class Swagger2 {
}
3.啓動項目 測試 ：（訪問ui頁面路徑：localhost：8080/swagger-ui.html ）
完事了！！！ 這就成功了 。
真正開發情況下，swagger配置得配全面。繼續往下看把。
@Configuration //等價於 @Component
@EnableSwagger2 //開啓swagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.yuqi.demo.controller")) //掃描指定接口所在得路徑
.paths(PathSelectors.any())
.build();
}
//編寫swagger 信息，可在ui頁面顯示
private ApiInfo apiInfo() {
Contact contact = new Contact("小健","https://blog.csdn.net/qq_35370485","[email protected]");
return new ApiInfoBuilder()
.title("服務APIs") //
.description("只有登上山峯，山纔會支撐你")
.termsOfServiceUrl("https://blog.csdn.net/qq_35370485")
.contact(contact) //作者信息
.version("1.0")
.build();
}
}
Controller層：
@RestController
@Component
@Api(value = "測試接口",tags = "測試") //
public class HelloController {
@RequestMapping("/hello")
public String testHello(){
return "hello";
}
}
swagger註解：
1、@Api()：用在請求的類上，表示對類的說明，也代表了這個類是swagger2的資源
參數：
tags：說明該類的作用，參數是個數組，可以填多個。
value="該參數沒什麼意義，在UI界面上不顯示，所以不用配置"
description = "用戶基本信息操作"
2、@ApiOperation()：用於方法，表示一個http請求訪問該方法的操作
參數：
value="方法的用途和作用"
notes="方法的注意事項和備註"
tags：說明該方法的作用，參數是個數組，可以填多個。
格式：tags={"作用1","作用2"}
（在這裏建議不使用這個參數，會使界面看上去有點亂，前兩個常用）
3、@ApiModel()：用於響應實體類上，用於說明實體作用
參數：
description="描述實體的作用"
4、@ApiModelProperty：用在屬性上，描述實體類的屬性
參數：
value="用戶名" 描述參數的意義
name="name" 參數的變量名
required=true 參數是否必選
5、@ApiImplicitParams：用在請求的方法上，包含多@ApiImplicitParam
6、@ApiImplicitParam：用於方法，表示單獨的請求參數
參數：
name="參數ming"
value="參數說明"
dataType="數據類型"
paramType="query" 表示參數放在哪裏
· header 請求參數的獲取：@RequestHeader
· query 請求參數的獲取：@RequestParam
· path（用於restful接口） 請求參數的獲取：@PathVariable
· body（不常用）
· form（不常用）
defaultValue="參數的默認值"
required="true" 表示參數是否必須傳
7、@ApiParam()：用於方法，參數，字段說明 表示對參數的要求和說明
參數：
name="參數名稱"
value="參數的簡要說明"
defaultValue="參數默認值"
required="true" 表示屬性是否必填，默認爲false
8、@ApiResponses：用於請求的方法上，根據響應碼錶示不同響應
一個@ApiResponses包含多個@ApiResponse
9、@ApiResponse：用在請求的方法上，表示不同的響應
參數：
code="404" 表示響應碼(int型)，可自定義
message="狀態碼對應的響應信息"
10、@ApiIgnore()：用於類或者方法上，不被顯示在頁面上
11、@Profile({"dev", "test"})：用於配置類上，表示只對開發和測試環境有用