喜歡Swagger，就是在前后端分離中，可以及時的在線同步更新api文檔，方便自己進行功能測試，
當然這是只是強大的Swagger的一部分，下面我帶著大家了解下Swagger，同時做一個spingboot-swagger的一個Demo，供大家參考。
什么是 Swagger
Swagger 是一個規范和完整的框架，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目標是使客戶端和文件系統作為服務器以同樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，允許API來始終保持同步
下面從官方的角度介紹下Swagger，這部分你也可以直接跳過。
The Best APIs are Built with Swagger Tools
最好的api是用Swagger構建的
官網地址：https://swagger.io/
Swagger 主要包含以下5部分組成.
-
Design - API Design
API Design
Design is the foundation of your API development. Swagger makes API design a breeze, with easy-to-use tools for developers, architects, and product owners.設計是API開發的基礎。Swagger使API設計變得輕而易舉，為開發人員、架構師和產品所有者提供了易于使 用的工具。
-
Build - API Development
API Development
Protocols, error handling, and code modularity are just some of the questions your teams need to address before building a great API. Swagger provides tools for quickly prototyping and building your API’s functionality.協議、錯誤處理和代碼模塊化只是團隊在構建優秀API之前需要解決的一些問題。Swagger提供了快速原型化和構建API功能的工具。
-
Document - API Documentation
API Documentation
Swagger takes the manual work out of API documentation, with a range of solutions for generating, visualizing, and maintaining API docs.
Swagger從API文檔中提取手工工作，并提供了一系列用于生成、可視化和維護API文檔的解決方案。
- Test - API Testing
API Testing
Start your functional, security, and performance testing right from the OpenAPI Spec. Swagger tooling and the ReadyAPI platform make it easy to rapidly create, manage, & execute API tests in your pipeline.
從OpenAPI規范開始您的功能、安全性和性能測試。Swagger工具和ReadyAPI平臺使得在您的管道中快速創建、管理和執行API測試變得容易。
- Standardize - Governance and Standardization
Governance and Standardization
People and processes make up a successful API program. Efficiently managing these efforts makes for good governance. Whether you have a team of five or five hundred, Swagger can help.
人員和流程構成了一個成功的API程序。有效地管理這些工作有助于良好的治理。不管你的團隊是5人還是500人，Swagger都能幫助到你。
快速上手
- 添加依賴
- 添加配置類SwaggerConfig
- 編寫一個controller 類
Spring Boot 集成 Swagger 2.X 很簡單，需要引入依賴并做基礎配置就可以了。
1. 添加依賴
<!--swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2. 添加配置類SwaggerConfig
/**
* SwaggerConfig.
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("top.lconcise.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("SpringBoot-Swagger api文檔")
.description("")
.termsOfServiceUrl("http://www.lxweimin.com/u/ce4cf486d279")
.version("1.0")
.build();
}
}
- @Configuration 配置類，啟動時加載此類
- @EnabledSwagger2 標識項目啟動 SwaggerApi 文檔
- ApiInfo 這個類時Swagger 頁面展示的一些基礎信息
- RequestHandlerSelectors.basePackage("top.lconcise.controller") 這里的top.lconcise.controller 是掃描包的路徑
3.編寫一個controller 類
package top.lconcise.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import top.lconcise.bus.entity.User;
import top.lconcise.bus.service.UserService;
import top.lconcise.view.Message;
@Api(value = "用戶相關操作", tags = "用戶相關操作")
@RestController
@RequestMapping("/users")
public class UserController {
@Autowired
private UserService userService;
@ApiOperation("創建用戶")
@PostMapping
public Message<String> create(@RequestBody User bean) {
return userService.create(bean);
}
@ApiOperation("修改用戶")
@PutMapping
public Message<String> put(@RequestBody User bean) {
return userService.update(bean);
}
@ApiOperation("獲取所有用戶")
@GetMapping
public Message findAll() {
return userService.findAll();
}
@ApiOperation("根據id刪除用戶")
@DeleteMapping(value = "/{id}")
public Message deleteById(@PathVariable("id") Long id) {
return userService.deletedById(id);
}
}
4. 啟動項目 訪問 http://127.0.0.1:8080/swagger-ui.html
效果如下圖
就可以很清楚看到用戶的相關接口，并進行接口測試。
