詳解Swagger接口文檔和常用注解的使用
更新時間：2022年08月08日 09:42:10 作者：張維鵬
Swagger是一款遵循?Restful?風格的接口文檔開發(fā)神器，支持基于?API?自動生成接口文檔。本文將為大家講講Swagger接口文檔和常用注解的使用方法，需要的可以參考一下
Swagger是一款遵循 Restful 風格的接口文檔開發(fā)神器，支持基于 API 自動生成接口文檔，接口文檔始終與 API 保持同步，不再需要手動編寫接口文檔，并且采用全注解的方式，開發(fā)簡單，代碼侵入性低，對服務端開發(fā)的程序員來說非常方便，可以節(jié)約大量寫接口文檔的時間。除此之外，Swagger 生成的文檔還支持在線測試，參數(shù)和格式都定好了，直接在界面上輸入?yún)?shù)對應的值即可在線測試接口。
一、Spring整合Swagger
（1）在 pom.xml 文件中添加 Swagger 的 maven 依賴：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
（2）編寫Swagger自定義配置類：
/**
* 類說明 :自定義swagger配置信息
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket creatApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select() //選擇哪些路徑和api會生成document
.apis(RequestHandlerSelectors.basePackage("com.zwp.controller"))//controller路徑
//.apis(RequestHandlerSelectors.any()) //對所有api進行監(jiān)控
.paths(PathSelectors.any()) //對所有路徑進行監(jiān)控
.build();
}
//接口文檔的一些基本信息
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("springmvc+swagger整合")//文檔主標題
.description("test接口文檔")//文檔描述
.version("1.0.0")//API的版本
.termsOfServiceUrl("###")
.license("LICENSE")
.licenseUrl("###")
.build();
}
}在 springmvc.xml 文件中配置創(chuàng)建對象：
<!-- 使用注解驅動：自動配置處理器映射器與處理器適配器 --> <mvc:annotation-driven /> <!-- 注解方式：自動掃描該包 --> <context:component-scan base-package="com.zwp.config" />
（3）在 springmvc.xml 中過濾掉 swagger-ui 的靜態(tài)資源文件：
<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" /> <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/" />
（4）在controller類添加swagger的注解：
//在類上面加@Api注解，表明該controller類需要被swagger自動生成文檔
@Api(tags="UserController",description="user的控制層")
@Controller
@RequestMapping("/user")
public class UserController {
@Autowired
private UserService userService;
//在方法上面添加@ApiOperation注解，表明該方法需要被swagger自動生成文檔
@ApiOperation(httpMethod="GET",value="接口標題:獲取用戶信息",notes="接口的notes說明：需要user的id")
@RequestMapping(value="/getUserById/{userId}",method=RequestMethod.GET)
public @ResponseBody User getUserById(@PathVariable Integer userId){
return userService.getUserById(userId);
}
}（5）部署工程，訪問路徑：
格式：http://服務器ip:端口/項目名稱//swagger-ui.html
例子：http://localhost:8080/ssm/swagger-ui.html
見到上面頁面，表示整合成功。
二、swagger常用注解說明
| 注解 | 說明 |
| @Api | 修飾controller類，標識這個類是swagger的資源 |
| @ApiOperation | 修飾controller的方法，表示一個http請求的操作 |
| @ApiParam | 修飾方法的參數(shù)，用于添加參數(shù)說明與是否必填等元數(shù)據(jù) |
| @ApiModel | 修飾對象類，表示對對象類進行說明，用于參數(shù)用實體類接收的場景 |
| @ApiModelProperty | 修飾對象類中的屬性，對屬性進行說明 |
| @ApiIgnore() | 修飾類、方法、參數(shù)等，表示不顯示在swagger文檔中 |
| @ApiImplicitParam | 用于方法，表示單獨的請求參數(shù) |
| @ApiImplicitParams | 用于方法，包含多個 @ApiImplicitParam |
1、@Api的使用說明
修飾controller類，標識這個類是swagger的資源，屬性說明：
tags：類的說明，但是tags如果有多個值，會生成多個list
value：也是類的說明，可以使用tags替代
@Api(value="用戶controller",tags={"用戶操作接口"})
@RestController
public class UserController {
}
效果圖：
2、@ApiOperation的使用說明
修飾controller的方法，表示一個http請求的操作，屬性說明：
value：用于方法描述
notes：用于提示內容
tags：可以重新分組，視情況而用）
3、@ApiParam的使用說明
修飾方法的參數(shù)，用于添加參數(shù)說明與是否必填等元數(shù)據(jù)，屬性說明：
name：參數(shù)名
value：參數(shù)說明
required：是否必填
@Api(value="用戶controller",tags={"用戶操作接口"})
@RestController
public class UserController {
@ApiOperation(value="獲取用戶信息",tags={"獲取用戶信息copy"},notes="注意問題點")
@GetMapping("/getUserInfo")
public User getUserInfo(@ApiParam(name="id",value="用戶id",required=true) Long id,@ApiParam(name="username",value="用戶名") String username) {
// userService可忽略，是業(yè)務邏輯
User user = userService.getUserInfo();
return user;
}
}
效果圖：
4、@ApiModel的使用說明
修飾對象類，表示對對象類進行說明，用于參數(shù)用實體類接收的場景，屬性說明：
value：表示對象名，可省略
description：描述，可省略
5、@ApiModelProperty的使用說明
修飾對象類中的屬性，對屬性進行說明，屬性說明：
- value：字段說明
- name：重寫屬性名字
- dataType：重寫屬性類型
- required：是否必填
- example：舉例說明
- hidden：是否隱藏
@ApiModel(value="user對象",description="用戶對象user")
public class User implements Serializable{
private static final long serialVersionUID = 1L;
@ApiModelProperty(value="用戶名",name="username",example="xingguo")
private String username;
@ApiModelProperty(value="狀態(tài)",name="state",required=true)
private Integer state;
private String password;
private String nickName;
private Integer isDeleted;
@ApiModelProperty(value="id數(shù)組",hidden=true)
private String[] ids;
private List<String> idList;
} @ApiOperation("更改用戶信息")
@PostMapping("/updateUserInfo")
public int updateUserInfo(@RequestBody @ApiParam(name="用戶對象",value="傳入json格式",required=true) User user){
int num = userService.updateUserInfo(user);
return num;
}
效果圖：
6、@ApiIgnore的使用說明
修飾類、方法、參數(shù)等，表示不顯示在swagger文檔中，比較簡單, 這里不做舉例
7、@ApiImplicitParam的使用說明
用于方法，表示單獨的請求參數(shù)
8、@ApiImplicitParams的使用說明
用于方法，包含多個 @ApiImplicitParam，屬性說明：
- name：參數(shù)ming
- value：參數(shù)說明
- dataType：數(shù)據(jù)類型
- paramType：參數(shù)類型
- example：舉例說明
@ApiOperation("查詢測試")
@GetMapping("select")
//@ApiImplicitParam(name="name",value="用戶名",dataType="String", paramType = "query")
@ApiImplicitParams({
@ApiImplicitParam(name="name",value="用戶名",dataType="string", paramType = "query",example="xingguo"),
@ApiImplicitParam(name="id",value="用戶id",dataType="long", paramType = "query")})
public void select(){
}
效果圖：
9、@ApiResponses與@ApiResponse使用說明
這兩個注解都表示對響應結果進行說明
10、@RequestMapping注解的推薦配置
value、method、produces
示例：
@ApiOperation("信息軟刪除")
@ApiResponses({ @ApiResponse(code = CommonStatus.OK, message = "操作成功"),
@ApiResponse(code = CommonStatus.EXCEPTION, message = "服務器內部異常"),
@ApiResponse(code = CommonStatus.FORBIDDEN, message = "權限不足") })
@ApiImplicitParams({ @ApiImplicitParam(paramType = "query", dataType = "Long", name = "id", value = "信息id", required = true) })
@RequestMapping(value = "/remove.json", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
public RestfulProtocol remove(Long id) {以上就是詳解Swagger接口文檔和常用注解的使用的詳細內容，更多關于Swagger接口文檔 注解的資料請關注腳本之家其它相關文章！
相關文章
這篇文章主要介紹了JAVA?module-info.java文件詳解，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2022-01-01
這篇文章主要介紹了關于Java鎖性能提高(鎖升級)機制的總結，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2022-05-05
這篇文章主要介紹了Springboot主程序類注解配置過程圖解,文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值,需要的朋友可以參考下2020-10-10
本篇文章主要介紹了java中的文件操作總結（干貨），主要有文件讀寫，遍歷文件夾，文件夾操作等，具有一定的參考價值，感興趣的小伙伴們可以參考一下。2017-02-02
這篇文章主要介紹了Java的異常測試框架JUnit使用上手指南,JUnit是Java代碼進行單元測試中的常用工具,需要的朋友可以參考下2016-03-03
spring-boot整合Micrometer+Prometheus的詳細過程
這篇文章主要介紹了springboot整合Micrometer+Prometheus的詳細過程,本文通過實例代碼給大家介紹的非常詳細,對大家的學習或工作具有一定的參考借鑒價值,需要的朋友參考下吧2024-05-05
這篇文章主要介紹了Java IO流，同時也介紹了流中的一些相關的內容，并且通過大量的案例供大家理解。最后通過一些經典的案例幫助大家對前面所學的知識做了一個綜合的應用,需要的朋友可以參考一下2022-05-05
Spring 單元測試中如何進行 mock的實現(xiàn)
這篇文章主要介紹了Spring 單元測試中如何進行 mock的實現(xiàn)，文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值，需要的朋友們下面隨著小編來一起學習學習吧2020-12-12
基于javaweb+jsp的游泳館會員管理系統(tǒng)(附源碼)
這篇文章主要介紹了基于javaweb+jsp的游泳館會員管理系統(tǒng),開發(fā)工具eclipse/idea/myeclipse/sts等均可配置運行，此源代碼社和課程設計，大作業(yè)及畢業(yè)設計項目，需要的朋友可以參考下2022-04-04
Java發(fā)送form-data請求實現(xiàn)文件上傳
這篇文章主要為大家詳細介紹了Java發(fā)送form-data請求實現(xiàn)文件上傳，文中示例代碼介紹的非常詳細，具有一定的參考價值，感興趣的小伙伴們可以參考一下2022-06-06