Swagger 是一款RESTFUL接口的文檔在線自動生成+功能測試功能軟件。?Swagger 是一個規范和完整的框架，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目標是使客戶端和文件系統作為服務器以同樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，允許API來始終保持同步。Swagger 讓部署管理和使用功能強大的API從未如此簡單。

?

一、springmvc+swagger的整合：

（1）在pom.xml中添加swagger的jar包依賴：

<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 {@Beanpublic Docket creatApi(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select() //選擇哪些路徑和api會生成document.apis(RequestHandlerSelectors.basePackage("com.zwp.controller"))//controller路徑//.apis(RequestHandlerSelectors.any()) //對所有api進行監控.paths(PathSelectors.any()) //對所有路徑進行監控.build();}//接口文檔的一些基本信息private ApiInfo apiInfo() {return new ApiInfoBuilder().title("springmvc+swagger整合")//文檔主標題.description("test接口文檔")//文檔描述.version("1.0.0")//API的版本.termsOfServiceUrl("###").license("LICENSE").licenseUrl("###").build();} }

在springmvc.xml文件中配置創建對象：

<!-- 使用注解驅動：自動配置處理器映射器與處理器適配器 --> <mvc:annotation-driven /> <!-- 注解方式：自動掃描該包 --> <context:component-scan base-package="com.zwp.config" />

（3）在springmvc.xml中過濾掉swagger-ui的靜態資源文件：

<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" /> <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/" />

（4）在controller的類中進行相關的配置：

//需要在類上面加@Api注解，表明該controller類需要被swagger自動生成文檔 @Controller @RequestMapping("/user") @Api(tags="UserController",description="user的控制層") public class UserController {@Autowiredprivate 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常用注解說明：?

該部分的內容轉自：https://blog.csdn.net/u014231523/article/details/76522486

• @Api()用于controller類，標識這個類是swagger的資源?
• @ApiOperation()用于controller的方法，表示一個http請求的操作?
• @ApiParam()用于方法，參數，字段說明，表示對參數的添加元數據（說明或是否必填等）?
• @ApiModel()用于類，表示對類進行說明，用于參數用實體類接收?
• @ApiModelProperty()用于方法，字段。表示對model屬性的說明或者數據操作更改?
• @ApiIgnore()用于類，方法，方法參數。表示這個方法或者類被忽略?
• @ApiImplicitParam()?用于方法，表示單獨的請求參數?
• @ApiImplicitParams()?用于方法，包含多個 @ApiImplicitParam

具體使用舉例說明：?

1、@Api()的使用說明：

@Api()用于類，標識這個類是swagger的資源?

屬性說明：

• tags，表示說明；但是tags如果有多個值，會生成多個list
• value也是說明，可以使用tags替代

@Api(value="用戶controller",tags={"用戶操作接口"}) @RestController public class UserController {}

?效果圖：?

?

2、@ApiOperation()的使用說明：

@ApiOperation()用于方法；表示一個http請求的操作

屬性說明：

• value用于方法描述?
• notes用于提示內容?
• tags可以重新分組（視情況而用）?

3、@ApiParam()的使用說明：

@ApiParam()用于方法，參數，字段說明；表示對參數的添加元數據（說明是否必填等）?

屬性說明

• name–參數名?
• value–參數說明?
• 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可忽略，是業務邏輯User user = userService.getUserInfo();return user;} }

效果圖：?

?

4、@ApiModel()的使用說明：

@ApiModel()用于類；表示對類進行說明，用于參數用實體類接收?

屬性說明：

• value–表示對象名，可省略
• description–描述，可省略

5、@ApiModelProperty()的使用說明：

@ApiModelProperty()用于方法，字段；表示對model屬性的說明或者數據操作更改

屬性說明：

• 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="狀態",name="state",required=true)private Integer state;private String password;private String nickName;private Integer isDeleted;@ApiModelProperty(value="id數組",hidden=true)private String[] ids;private List<String> idList;//省略get/set } @ApiOperation("更改用戶信息")@PostMapping("/updateUserInfo")public int updateUserInfo(@RequestBody @ApiParam(name="用戶對象",value="傳入json格式",required=true) User user){int num = userService.updateUserInfo(user);return num;}

效果圖：?

?

6、@ApiIgnore()的使用說明：

@ApiIgnore()用于類或者方法上，可以不被swagger顯示在頁面上，比較簡單, 這里不做舉例

?

7、@ApiImplicitParam()的使用說明：

@ApiImplicitParam()用于方法，表示單獨的請求參數

8、@ApiImplicitParams()的使用說明：

@ApiImplicitParams()用于方法，包含多個@ApiImplicitParam

屬性說明：

• name：參數ming?
• value：參數說明?
• dataType：數據類型?
• paramType：參數類型?
• 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) { @ApiModelProperty(value = "標題")private String title;

?

總結

以上是生活随笔為你收集整理的springmvc整合swagger 与 常用注解说明的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。