Swagger使用
1. Spring MVC配置文件中的配置
<mvc:annotation-driven/>
<context:component-scan base-package="com.demo"/>
设置使用注解的类所在的jar包,只加载controller类
<mvc:default-servlet-handler />
使用 Swagger Restful API文档时,添加此注解
2. maven依赖
<properties> <spring.version>4.2.6.RELEASE</spring.version> <servlet.version>3.1.0</servlet.version> <swagger2.version>2.5.0</swagger2.version> </properties> <dependencies> <!-- swagger开始 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>${swagger2.version}</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>${swagger2.version}</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-staticdocs</artifactId> <version>${swagger2.version}</version> </dependency> <!-- swagger结束 --> <!--spring--> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-core</artifactId> <version>${spring.version}</version> </dependency> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-web</artifactId> <version>${spring.version}</version> </dependency> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-webmvc</artifactId> <version>${spring.version}</version> </dependency> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-beans</artifactId> <version>${spring.version}</version> </dependency> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-context</artifactId> <version>${spring.version}</version> </dependency> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-context-support</artifactId> <version>${spring.version}</version> </dependency> <!--web--> <dependency> <groupId>javax.servlet</groupId> <artifactId>javax.servlet-api</artifactId> <version>${servlet.version}</version> <scope>provided</scope> </dependency> </dependencies> |
3. Swagger注解配置
@RequestMapping(value = "/add", method = RequestMethod.POST) @ApiOperation(value = "添加用户", notes = "增加用户") public Result<UserVo> add(@ApiParam(name = "userName",value = "用户昵称",required = true)@RequestParam(name = "userName",required = true)String userName, @ApiParam(name = "mobile",value = "手机",required = true)@RequestParam(name = "mobile",required = true)String mobile, @ApiParam(required = true, name = "email", value = "邮箱") @RequestParam(name = "email", required = true) String email ) { UserVo userVo=new UserVo(); userVo.setUserId(System.currentTimeMillis()); userVo.setUserName(userName); return new Result<UserVo>(Constants.SUCCESS,Constants.MSG_SUCCESS,userVo); } |
@ApiOperation(value = "创建用户", notes = "根据UserVo对象创建用户") @RequestMapping(value = "/create", method = RequestMethod.POST) public String postUser(@ApiParam(required = true, name = "userVo", value = "实体UserVo") @RequestBody UserVo userVo) { return "success"; } |
@RequestMapping(value = "/getUser", method = RequestMethod.GET) @ApiOperation(value = "获取用户", notes = "根据UserVo获取用户") @ResponseBody public Result<UserVo> getUser() { UserVo userVo=new UserVo(); userVo.setUserId(System.currentTimeMillis()); userVo.setUserName("UserName"); return new Result<UserVo>(Constants.SUCCESS,Constants.MSG_SUCCESS,userVo); } |
SwaggerConfig类编写示例
@Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket userApi() { return new Docket(DocumentationType.SWAGGER_2) .groupName("用户") .select() // 选择那些路径和api会生成document .apis(RequestHandlerSelectors.basePackage("com.zyx.controller")) .paths(PathSelectors.any()) // 对所有路径进行监控 .build() .apiInfo(userInfo()); } private ApiInfo userInfo() { ApiInfo apiInfo = new ApiInfo("用户相关接口",//大标题 "用户有关的接口,包括增加删除用户",//小标题 "0.1",//版本 "杭州", new Contact("zyx", "", ""),// 作者 "swagger url",//链接显示文字 ""//网站链接 ); return apiInfo; } @Bean public Docket otherApi() { return new Docket(DocumentationType.SWAGGER_2) .groupName("其它") .select() // 选择那些路径和api会生成document .apis(RequestHandlerSelectors.basePackage("com.zyx.controller")) .paths(PathSelectors.any()) // 对所有路径进行监控 .build() .apiInfo(otherInfo()); } private ApiInfo otherInfo() { ApiInfo apiInfo = new ApiInfo("其它相关接口",//大标题 "其它有关的接口,包括增加删除其它",//小标题 "0.1",//版本 "杭州", new Contact("zyx_other", "", ""),// 作者 "点击",//链接显示文字 ""//网站链接 ); return apiInfo; } } |
注:将SwaggerConfig在Spring注入管理 <bean class="com.demo.config.SwaggerConfig"/>
@ApiModel(value = "用户信息") public class UserVo { @ApiModelProperty(value = "用户id", required = true) private long userId; @ApiModelProperty(value = "昵称", required = true) private String userName; public long getUserId() { return userId; } public void setUserId(long userId) { this.userId = userId; } public String getUserName() { return userName; } public void setUserName(String userName) { this.userName = userName; } } |
4. 界面展示