Swagger-API文檔接口引擎
Swagger是什么
Swagger是一個規范和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目標是使客戶端和文件系統作為服務器以同樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，允許API來始終保持同步。
在項目開發中，根據業務代碼自動生成API文檔，給前端提供在線測試，自動顯示JSON格式，方便了后端與前端的溝通與調試成本。
Swagger有一個缺點就是侵入性模式，必須配置在具體的代碼里。
Swagger使用（SpringBoot+Swagger集成）
新建Maven項目
第一種方式：使用第三方依賴
1.在pom.xml文件中添加第三方swagger依賴
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.7.0.RELEASE</version>
</dependency>
2、在Spring Boot項目的啟動類上添加@EnableSwagger2，啟動Swagger
3、https://github.com/SpringForAll/spring-boot-starter-swagger，GitHub上這個swagger依賴實現的項目，里面有詳細的講解。
第二種方式：使用官方依賴
1.在pom.xml文件中添加swagger相關依賴
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>org.codehaus.jackson</groupId>
<artifactId>jackson-core-asl</artifactId>
<version>1.9.13</version>
</dependency>
第一個是API獲取的包
第二是官方給出的一個ui界面，這個界面可以自定義，默認是官方的
第三個是測試數據以JSON格式返回的依賴包
2.配置Swagger
新建Swagger配置類，需要特別注意的是Swagger scan base package,這是掃描注解的配置，即你的API接口位置，對前端提供服務接口的位置。
package com.example.demo.config;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("API接口文檔")
.description("用戶信息管理")
.version("1.0.0")
.build();
}
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) //這里寫的是API接口所在的包位置
.paths(PathSelectors.any())
.build();
}
}
3.簡單寫個Dao和User實體類
package com.example.demo.dao;
import com.example.demo.entity.User;
public interface UserDao {
User findById(Integer id);
User findByName(String name);
}
public class User {
int id;//用戶ID
String name;//姓名
public void setId(int id){
this.id=id;
}
public int getId(){
return id;
}
public void setName(String name){
this.name=name;
}
public String getName(){
return name;
}
4.撰寫Controller（UserController）
@RestController
@RequestMapping("/user")
@Api(value = "用戶信息管理")
public class UserController {
UserDao userDao;
@RequestMapping(method = RequestMethod.POST,value = "/userById")
@ApiOperation(value = "獲取用戶信息", notes = "通過用戶ID獲取用戶信息")
public Object findById(@ApiParam(value = "用戶ID",required = true) int id){
return userDao.findById(id);
}
@RequestMapping(method = RequestMethod.POST,value = "/userByName")
@ApiOperation(value = "獲取用戶信息", notes = "通過用戶姓名獲取用戶信息")
public Object findByName(@ApiParam(value = "用戶姓名",required = true) String name){
return userDao.findByName(name);
}
}
5.設定訪問API文檔的路由
在配置文件中，application.yml中聲明：
springfox.documentation.swagger.v2.path: /api-docs
這個path就是json的訪問request mapping.可以自定義，防止與自身代碼沖突。
API doc的顯示路由是：http://localhost:8080/swagger-ui.html
Swagger常用注解
1、Api標記
Api 用在類上，說明該類的作用。可以標記一個Controller類做為swagger 文檔資源，使用方式：
@Api(value = "/user", description = "Operations about user")
2、ApiOperation標記
ApiOperation：用在方法上，說明方法的作用，每一個url資源的定義,使用方式：
@ApiOperation(
value = "Find purchase order by ID",
notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
response = Order,
tags = {"Pet Store"})
3、ApiParam標記
ApiParam請求屬性,使用方式：
public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true) User user)
4. ApiResponse
ApiResponse：響應配置，使用方式：
@ApiResponse(code = 400, message = "Invalid user supplied")
5. ApiResponses
ApiResponses：響應集配置，使用方式：
@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
6. ResponseHeader
響應頭設置，使用方法
@ResponseHeader(name="head1",description="response head conf")
@Api()用於類；
表示標識這個類是swagger的資源
@ApiOperation()用於方法；
表示一個http請求的操作
@ApiParam()用於方法，參數，字段說明；
表示對參數的添加元數據（說明或是否必填等）
@ApiModel()用於類
表示對類進行說明，用於參數用實體類接收
@ApiModelProperty()用於方法，字段
表示對model屬性的說明或者數據操作更改
@ApiIgnore()用於類，方法，方法參數
表示這個方法或者類被忽略
@ApiImplicitParam() 用於方法
表示單獨的請求參數
@ApiImplicitParams() 用於方法，包含多個 @ApiImplicitParam
@Api()
用於類；表示標識這個類是swagger的資源
tags–表示說明
value–也是說明，可以使用tags替代
但是tags如果有多個值，會生成多個list
@Api(value="用戶controller",tags={"用戶操作接口"})
@RestController
public class UserController {
}
@ApiOperation() 用於方法；表示一個http請求的操作
value用於方法描述
notes用於提示內容
tags可以重新分組（視情況而用）
@ApiParam() 用於方法，參數，字段說明；表示對參數的添加元數據（說明或是否必填等）
name–參數名
value–參數說明
required–是否必填
@ApiModel()用於類 ；表示對類進行說明，用於參數用實體類接收
value–表示對象名
description–描述
都可省略
@ApiModelProperty()用於方法，字段； 表示對model屬性的說明或者數據操作更改
value–字段說明
name–重寫屬性名字
dataType–重寫屬性類型
required–是否必填
example–舉例說明
hidden–隱藏
@ApiIgnore()用於類或者方法上，可以不被swagger顯示在頁面上
比較簡單, 這里不做舉例
@ApiImplicitParam() 用於方法
表示單獨的請求參數
@ApiImplicitParams() 用於方法，包含多個 @ApiImplicitParam
name–參數ming
value–參數說明
dataType–數據類型
paramType–參數類型
example–舉例說明
————————————————
參考鏈接：https://blog.csdn.net/ai_miracle/article/details/82709949