Swagger2-生成RESTful接口文档

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。

1. 引入依赖

1
2
3
4
5
6
7
8
9
10
<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>

2.配置Swagger2

在 Application.java 同级创建 Swagger2.java(同级创建该文件会导致项目目录结构不整洁,在config目录下创建呢?)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
@Configuration
@EnableSwagger2
public class Swagger2 {

@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("cn.caoler.kiv.controller"))
.paths(PathSelectors.any())
.build();
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot添加Swagger2组件")
.description("Spring Boot添加Swagger2组件")
.version("1.0")
.build();
}

}

其中 .apis(RequestHandlerSelectors.basePackage(“cn.caoler.kiv.controller”)) 指定了以扫描包的方式进行,会把cn.caoler.kiv.controller包下的controller都扫描到。

@configration 标识这是一个配置类

@EnableSwagger2开启swagger2

PathSelectors.any()表示路径选择器匹配所有路径

apiInfo() swagger页面上的一些展示信息

3.举例

1
2
3
4
5
6
7
8
9
10
11
12
@ApiOperation(value = "新建用户", notes = "新建一个用户")
@ApiImplicitParams({
@ApiImplicitParam(name = "user", value = "用户数据", required = true,dataType = "User")
@ApiImplicitParam(name = "page", value = "页码", required = true,dataType = "Integer")
})
@RequestMapping(value = "/create", method = RequestMethod.POST)
public Object create(@RequestBody User user
@RequsstParam(value = "page") Integer page) {
System.out.println("user : " + user.getName());
System.out.println(page);
return 1;
}

4.常用注释

@Api() 用于类;表示标识这个类是swagger的资源

  • tags–表示说明
  • value–也是说明,可以使用tags替代

@ApiOperation() 用于方法;表示一个http请求的操作

  • value用于方法描述
  • notes用于提示内容

@ApiParam() 用于方法,参数,字段说明;表示对参数的添加元数据(说明或是否必填等)

  • name–参数名
  • value–参数说明
  • required–是否必填

@ApiModel()用于类 ;表示对类进行说明,用于参数用实体类接收

  • value–表示对象名

@ApiModelProperty()用于方法,字段; 表示对model属性的说明或者数据操作更改

  • value–字段说明
  • name–重写属性名字
  • dataType–重写属性类型
  • required–是否必填
  • example–举例说明
  • hidden–隐藏

@ApiImplicitParam() 用于方法

  • 表示单独的请求参数

@ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam

  • name–参数ming
  • value–参数说明
  • dataType–数据类型
  • paramType–参数类型
  • example–举例说明

@ApiIgnore

  • 作用于方法上,使用这个注解swagger将忽略这个接口

5. SwaggerUI访问404错误

在按照网上教程配置好Swagger之后,在localhost:8080/swagger-ui.html 访问即可看到swagger页面了。

但是我第一次按照这样的方法配置却提示如下错误:

1
2
3
4
5
6
7
Whitelabel Error Page

This application has no explicit mapping for /error, so you are seeing this as a fallback.

Thu Nov 24 19:57:13 CST 2016
There was an unexpected error (type=Not Found, status=404).
No message available

出现404不是说文件没有,而是映射出现了问题,特别是静态文件映射。

解决方法:

在WebMvcConfig下添加如下代码:(若没有创建此拦截器,创建并extends WebMvcConfigurerAdapter)

1
2
3
4
5
6
7
8
9
@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);
}

6.参考

0%