swagger是什么涎嚼？
隨著互聯(lián)網(wǎng)技術(shù)的發(fā)展阱州，現(xiàn)在的網(wǎng)站架構(gòu)基本都由原來的后端渲染，變成了：前端渲染法梯、先后端分離的形態(tài)苔货，而且前端技術(shù)和后端技術(shù)在各自的道路上越走越遠(yuǎn)。
前端和后端的唯一聯(lián)系立哑，變成了API接口夜惭；API文檔變成了前后端開發(fā)人員聯(lián)系的紐帶，變得越來越重要铛绰，swagger就是一款讓你更好的書寫API文檔的框架诈茧。
swagger優(yōu)點？
- 完全實現(xiàn)了前后端交互的實時性捂掰，可以隨時對更改的接口文檔進(jìn)行查看敢会，防止出現(xiàn)調(diào)用接口失誤。
- 前端人員可以自行在網(wǎng)站上進(jìn)行測試
- 可以自動生成你想要的語言模式这嚣，便于切換
框架說明及使用
現(xiàn)在SWAGGER官網(wǎng)主要提供了幾種開源工具鸥昏，提供相應(yīng)的功能〗阒悖可以通過配置甚至是修改源碼以達(dá)到你想要的效果吏垮。
- Swagger Codegen
通過Codegen 可以將描述文件生成html格式和cwiki形式的接口文檔，同時也能生成多鐘語言的服務(wù)端和客戶端的代碼罐旗。支持通過jar包膳汪，docker，node等方式在本地化執(zhí)行生成九秀。也可以在后面的Swagger Editor中在線生成遗嗽。 - Swagger UI
提供了一個可視化的UI頁面展示描述文件。接口的調(diào)用方颤霎、測試、項目經(jīng)理等都可以在該頁面中對相關(guān)接口進(jìn)行查閱和做一些簡單的接口請求。該項目支持在線導(dǎo)入描述文件和本地部署UI項目友酱。 - Swagger Editor
類似于markendown編輯器的編輯Swagger描述文件的編輯器晴音，該編輯支持實時預(yù)覽描述文件的更新效果。也提供了在線編輯器和本地部署編輯器兩種方式缔杉。 - Swagger Inspector
感覺和postman差不多锤躁，是一個可以對接口進(jìn)行測試的在線版的postman。比在Swagger UI里面做接口請求或详，會返回更多的信息系羞，也會保存你請求的實際請求參數(shù)等數(shù)據(jù)。 - Swagger Hub
集成了上面所有項目的各個功能霸琴，你可以以項目和版本為單位椒振，將你的描述文件上傳到Swagger Hub中。在Swagger Hub中可以完成上面項目的所有工作梧乘，需要注冊賬號澎迎，分免費版和收費版。
注：Springfox Swagger: Spring 基于swagger規(guī)范选调，可以將基于SpringMVC和Spring Boot項目的項目代碼夹供，自動生成JSON格式的描述文件。本身不是屬于Swagger官網(wǎng)提供的仁堪，在這里列出來做個說明哮洽，方便后面作一個使用的展開。
Springboot 2.X 整合 Swagger2
- 添加maven 依賴
<!-- 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>
@Configuration
@EnableSwagger2
public class Swagger2Config {
/**
* 創(chuàng)建swagger ui的摘要
*
* @return
*/
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// 掃描的class的包路徑
.apis(RequestHandlerSelectors.basePackage("com.wangyq.boot.controller"))
// 只掃描類上有API注解的class
// .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
// 只掃描方法上有ApiOperation注解的方法 //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
/**
* swagger ui的標(biāo)題信息
*
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("標(biāo)題")
.description("副標(biāo)題")
.version("1.0")
.build();
}
}
- 添加注解
@Controller
@RequestMapping("/test")
@Api(value = "/test", description = "Operations about test", tags = "測試管理")
public class TestController extends BaseController {
private Logger logger = LoggerFactory.getLogger(TestController.class);
@RequestMapping(value = "/testRateLimit5", method = {RequestMethod.GET})
@ResponseBody
@RateLimit(limitNum = 2)
@ApiOperation(value = "測試接口限流", notes = "每秒鐘限流5 token", httpMethod = "GET")
@ApiImplicitParams({
@ApiImplicitParam(name = "data", value = "返回的數(shù)據(jù)對象", dataType = "Object"),
@ApiImplicitParam(name = "msg", value = "消息", dataType = "String"),
@ApiImplicitParam(name = "code", value = "狀態(tài)碼", dataType = "Integer")
})
public Result testRateLimit5() {
logger.info("調(diào)用了 testRateLimit5 方法");
return ResultUtil.success("調(diào)用了 testRateLimit5 方法弦聂！");
}
@GetMapping(value = "/testRateLimit10")
@RateLimit(limitNum = 10)
public Result testRateLimit10() {
logger.info("調(diào)用了 testRateLimit10 方法");
return ResultUtil.success("調(diào)用了 testRateLimit10 方法鸟辅！");
}
}
- 啟動springboot項目，訪問http://[ip]:[port]/swagger-ui.html横浑，如：http://localhost:8080/swagger-ui.html
swagger在spring中常用注解說明
- Api剔桨、ApiIgnore
- ApiModel
- ApiModelProperty
- ApiOperation
- ApiParam、ApiImplicitParam徙融、ApiImplicitParams
- ApiResponse
- ApiResponses
- ResponseHeader
- @Api
Api注解用于類上洒缀，說明該類的作用∑奂剑可以標(biāo)記一個Controller類做為swagger 文檔資源树绩。與Controller注解并列使用。
@Api(value = "/test", description = "Operations about test", tags = "測試管理") @Controller
@Api.png
ApiModel
ApiModel注解用于表示對類進(jìn)行說明隐轩，描述一個Model的信息饺饭，表示參數(shù)用實體類接收。ApiModelProperty
ApiModelProperty注解用于方法职车、字段瘫俊，表示對model屬性的說明或者數(shù)據(jù)操作更改鹊杖，配合ApiModel一起使用。-
ApiOperation
ApiOperation注解扛芽，用在方法上骂蓖，說明方法的作用，與Controller中的方法并列使用川尖。
ApiOperation.png
ApiImplicitParams
ApiImplicitParams注解用于方法上包含一組參數(shù)說明登下。-
ApiParam
ApiParam注解用在@ApiImplicitParams的方法里邊，屬性配置：
@ApiParam.png
-
ApiImplicitParam
ApiImplicitParam注解用于描述請求參數(shù)叮喳，根據(jù)不同的paramType類型被芳，請求的參數(shù)來源不同。屬性及取值如下：
@ApiImplicitParam.png
-
ApiResponse
ApiResponse注解用于響應(yīng)配置馍悟，與Controller中的方法并列使用畔濒。屬性配置：
ApiResponse.png
ApiResponses
ApiResponses注解中包含ApiResponse，用于描述一組ApiResponse值赋朦。-
ResponseHeader
ResponseHeader注解用于設(shè)置響應(yīng)頭篓冲，與Controller中的方法并列使用。 屬性配置：
ResponseHeader.png
- ApiIgnore
ApiIgnore注解用于類或方法上宠哄，表示不需要swagger處理壹将。
