Swagger 是一款RESTFUL接口的文檔在線自動(dòng)生成+功能測(cè)試功能軟件。?Swagger 是一個(gè)規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)。總體目標(biāo)是使客戶端和文件系統(tǒng)作為服務(wù)器以同樣的速度來更新。文件的方法，參數(shù)和模型緊密集成到服務(wù)器端的代碼，允許API來始終保持同步。Swagger 讓部署管理和使用功能強(qiáng)大的API從未如此簡(jiǎn)單。

?

一、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會(huì)生成document.apis(RequestHandlerSelectors.basePackage("com.zwp.controller"))//controller路徑//.apis(RequestHandlerSelectors.any()) //對(duì)所有api進(jìn)行監(jiān)控.paths(PathSelectors.any()) //對(duì)所有路徑進(jìn)行監(jiān)控.build();}//接口文檔的一些基本信息private ApiInfo apiInfo() {return new ApiInfoBuilder().title("springmvc+swagger整合")//文檔主標(biāo)題.description("test接口文檔")//文檔描述.version("1.0.0")//API的版本.termsOfServiceUrl("###").license("LICENSE").licenseUrl("###").build();} }

在springmvc.xml文件中配置創(chuàng)建對(duì)象：

<!-- 使用注解驅(qū)動(dòng)：自動(dòng)配置處理器映射器與處理器適配器 --> <mvc:annotation-driven /> <!-- 注解方式：自動(dòng)掃描該包 --> <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的類中進(jìn)行相關(guān)的配置：

//需要在類上面加@Api注解，表明該controller類需要被swagger自動(dòng)生成文檔 @Controller @RequestMapping("/user") @Api(tags="UserController",description="user的控制層") public class UserController {@Autowiredprivate UserService userService;//需要在方法上面添加@ApiOperation注解，表明該方法需要被swagger自動(dòng)生成文檔。@ApiOperation(httpMethod="GET",value="接口標(biāo)題:獲取用戶信息",notes="接口的notes說明：需要user的id")@RequestMapping(value="/getUserById/{userId}",method=RequestMethod.GET)public @ResponseBody User getUserById(@PathVariable Integer userId){return userService.getUserById(userId);}}

（5）部署工程，訪問路徑：

格式：http://服務(wù)器ip:端口/項(xiàng)目名稱//swagger-ui.html

例子：http://localhost:8080/ssm/swagger-ui.html

見到上面頁面，表示整合成功。

?

二、swagger常用注解說明：?

該部分的內(nèi)容轉(zhuǎn)自：https://blog.csdn.net/u014231523/article/details/76522486

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

具體使用舉例說明：?

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

@Api()用于類，標(biāo)識(shí)這個(gè)類是swagger的資源?

屬性說明：

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

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

?效果圖：?

?

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

@ApiOperation()用于方法；表示一個(gè)http請(qǐng)求的操作

屬性說明：

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

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

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

屬性說明

• name–參數(shù)名?
• value–參數(shù)說明?
• required–是否必填

@Api(value="用戶controller",tags={"用戶操作接口"}) @RestController public class UserController {@ApiOperation(value="獲取用戶信息",tags={"獲取用戶信息copy"},notes="注意問題點(diǎn)")@GetMapping("/getUserInfo")public User getUserInfo(@ApiParam(name="id",value="用戶id",required=true) Long id,@ApiParam(name="username",value="用戶名") String username) {// userService可忽略，是業(yè)務(wù)邏輯User user = userService.getUserInfo();return user;} }

效果圖：?

?

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

@ApiModel()用于類；表示對(duì)類進(jìn)行說明，用于參數(shù)用實(shí)體類接收?

屬性說明：

• value–表示對(duì)象名，可省略
• description–描述，可省略

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

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

屬性說明：

• value–字段說明
• name–重寫屬性名字
• dataType–重寫屬性類型
• required–是否必填
• example–舉例說明
• hidden–隱藏

@ApiModel(value="user對(duì)象",description="用戶對(duì)象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;//省略get/set } @ApiOperation("更改用戶信息")@PostMapping("/updateUserInfo")public int updateUserInfo(@RequestBody @ApiParam(name="用戶對(duì)象",value="傳入json格式",required=true) User user){int num = userService.updateUserInfo(user);return num;}

效果圖：?

?

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

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

?

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

@ApiImplicitParam()用于方法，表示單獨(dú)的請(qǐng)求參數(shù)

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

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

屬性說明：

• name：參數(shù)ming?
• value：參數(shù)說明?
• dataType：數(shù)據(jù)類型?
• paramType：參數(shù)類型?
• example：舉例說明

@ApiOperation("查詢測(cè)試")@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使用說明：

這兩個(gè)注解都表示對(duì)響應(yīng)結(jié)果進(jìn)行說明

?

10、@RequestMapping注解的推薦配置：

value、method、produces

示例：

@ApiOperation("信息軟刪除")@ApiResponses({ @ApiResponse(code = CommonStatus.OK, message = "操作成功"),@ApiResponse(code = CommonStatus.EXCEPTION, message = "服務(wù)器內(nèi)部異常"),@ApiResponse(code = CommonStatus.FORBIDDEN, message = "權(quán)限不足") })@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 = "標(biāo)題")private String title;

?

總結(jié)

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

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。