Springboot整合swagger2.8.0 在线API文档
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。用处:
1.自动生成在线文档
2.接口测试
整合过程
添加swagger2依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
创建swagger配置类
/**
* Swaggers 配置
*/
@Configuration
//启用swagger,生产环境请注释掉
@EnableSwagger2
public class Swaggers {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enableUrlTemplating(true)
.select()
// 扫描所有有注解的api,用这种方式更灵活
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
/**
* 首页描述
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("更多Spring Boot相关文章请百度:http://www.baidu.com")
.termsOfServiceUrl("http://www.baidu.com/")
.build();
}
}
@Configuration注解,让Spring来加载该类配置。再通过@EnableSwagger2注解启用Swagger2
在线文档添加
@RestController
@RequestMapping(value = "/users")
@Api(value = "用户测试信息", tags = {"用户测试相关接口"})//swagger控制器说明注解
public class UserController {
/**
* * 入参是对象,使用默认参数paramType = "body"
* ApiIgnore()用于类,方法,方法参数
* 表示这个方法或者类被忽略,不被显示在swagger页面上
* @param resp
* @param id
* @param user
* @return
*/
@ApiOperation(value = "更新用户详细信息", notes = "根据url的id来指定更新对象,并根据传过来的user信息来更新用户详细信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
})
@RequestMapping(value = "/{id}", method = RequestMethod.PUT)
public String putUser(@ApiIgnore ApiReturnInfo resp,@PathVariable Long id, @RequestBody User user) {
User u = users.get(id);
u.setName(user.getName());
u.setAge(user.getAge());
users.put(id, u);
return "success";
}
}
添加swagger注解之后,启动springboot服务,访问浏览器http://localhost:8080/swagger-ui.html 就可以看到在线的API文档。
swaggerUI访问404解决
重新指定静态资源,把swagger-ui.html页面加入
@Configuration
public class ServletContextConfig extends WebMvcConfigurationSupport {
/**
* 重新指定静态资源
* @param registry
*/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/**")
.addResourceLocations("classpath:/static/");
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
super.addResourceHandlers(registry);
}
}
使用体会
感觉在线文档生成倒是很好用,但swagger自带的接口测试不怎么好用,需要注意很多,
1、在接收参数的地方需要使用@RequestBody,才能接收,这点需要注意下;使用过springboot的同学都清楚,接收参数不需要加注解,就能接收。
2、如果存在多个参数类型,自定义对象及基础类型,这种数据即使使用@RequestBody,后台也是接收失败。目前还没找到解决方案,暂时只使用swagger2的在线文档,调试还是使用postman,汗颜…. ps:有解决方案的小伙伴请留言,不胜感激
完整demo请参考:springboot-swagger2-demo
swagger常用注解说明
- @Api()用于类;
表示标识这个类是swagger的资源 - @ApiOperation()用于方法;
表示一个http请求的操作 - @ApiParam()用于方法,参数,字段说明;
表示对参数的添加元数据(说明或是否必填等) - @ApiModel()用于类
表示对类进行说明,用于参数用实体类接收 - @ApiModelProperty()用于方法,字段
表示对model属性的说明或者数据操作更改 - @ApiIgnore()用于类,方法,方法参数
表示这个方法或者类被忽略 - @ApiImplicitParam() 用于方法
表示单独的请求参数 - @ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam