springfox整合swagger和spring

swagger_spring

springfox整合swagger和spring

使用springfox将SpringMVC与Swagger整合

项目源码见https://github.com/altraman00/swagger_spring

Swagger 是一系列对 RESTful 接口进行规范描述和页面展示的工具. 通过 springfox-swagger 将 Swagger 与 Spring-MVC 整合, 可从代码中的注解获取信息, 并生成相应的文档.

1、先添加依赖

<version.jackson>2.4.4</version.jackson>

<!--springfox-swagger需要的最小依赖 start-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.5.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.5.0</version>
</dependency>

<!--jackson用于将springfox返回的文档对象转换成JSON字符串-->
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-annotations</artifactId>
<version>${version.jackson}</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>${version.jackson}</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-core</artifactId>
<version>${version.jackson}</version>
</dependency>

<!--petStore是官方提供的一个代码参考, 可用于后期写文档时进行参考, 可不加-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-petstore</artifactId>
<version>2.5.0</version>
</dependency>
<!--最小依赖 end-->

springfox-swagger2 可以将代码中的注解转换为符合 Swagger 的 API 规范的 swagger.json 文件；

springfox-swagger-ui 提供了将 swagger.json 转换为 html 页面的服务.

最精简的 springfox 配置

Docket 对象为 spring-fox 提供了配置信息, ApiInfo 为生成的文档提供了元数据信息. 两者都使用这里我们仅仅使用最小配置, 两者均为默认配置. @EnableSwagger2 表示启用 Swagger.

@Configuration
@EnableSwagger2
public class MySwaggerConfig {
}

稍微增加点内容

@EnableWebMvc
@EnableSwagger2//启用Swagger2
@Configuration//让Spring来加载该类配置
@ComponentScan(basePackages ="com.swagger.doc.controller")
public class MySwaggerConfig {

@Bean
public Docket buildDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(buildApiInf())
.select()
.apis(RequestHandlerSelectors.basePackage("com.swagger.doc.controller"))//controller路径
.paths(PathSelectors.any())
.build();
}

private ApiInfo buildApiInf() {
return new ApiInfoBuilder()
.title("开放接口API")
.termsOfServiceUrl("https://resources/openapi/")
.description("项目名称等描述性词语")
.contact(new Contact("创建人@sina.cn", "https://项目官方地址.com/", "创建人@sina.cn"))
.version("1.0")
.build();

}
}

然后再在 spring-component.xml 配置文件中将这个类注册成 bean, 用于启用配置

<bean class="com.swagger.doc.MySwaggerConfig" />

这样就开启了 springfox 和 swagger.

springfox 的注解

写一个简单的 Controller

@Api(description = "User控制器")
@Controller
@RequestMapping("/user")
public class UserController {
@ApiOperation(value = "根据用户id查询用户信息", httpMethod = "GET", produces = "application/json")
@ApiResponse(code = 200, message = "success", response = Result.class)
@ResponseBody
@RequestMapping(value = "queryUserById", method = RequestMethod.GET, produces = "application/json")
public Result queryUserById(@ApiParam(name = "userId", required = true, value = "用户Id") @RequestParam("userId") int userId, HttpServletRequest request) {
User user = new User(userId, "haoyifen", 24);
Result result = new Result();
result.setCode(0);
result.setData(user);
result.setMessage("success");
return result;
}
}

常用的几个用于生成文档的注解如下:

- @Api 表示该类是一个 Swagger 的 Resource, 是对 Controller 进行注解的

- @ApiOperation 表示对应一个 RESTful 接口, 对方法进行注解

- @ApiResponse 表示对不同 HTTP 状态码的意义进行描述

- @ApiParam 表示对传入参数进行注解

注意：

在配置文件中，静态资源配置

<mvc:resources location="/,,classpath:/assets/" mapping="/**"></mvc:resources>

和

<mvc:default-servlet-handler/>

必须要配置一个，

如果直接使用，访问路径就为:http://{ip:端口}/{项目名}/swagger-ui.html就可以;

如果使用

<mvc:resources location="/,,classpath:/assets/" mapping="/assets/**">

，访问Swagger-ui.html时会出现接口名称等无法显示问题，

此时需要添加两行：

在springMVC-servlet中添加静态资源时配置如下：

以上配置将Web根路径”/”及类路径下 /META-INF/publicResources/ 的目录映射为/resources路径。假设Web根路径下拥有images、js这两个资源目录,在images下面有bg.gif图片，在js下面有test.js文件，则可以通过 /resources/images/bg.gif 和 /resources/js/test.js 访问这二个静态资源

全部配置完之后，访问地址如下：

访问 http://127.0.0.1:8080/swagger/swagger-ui.html 就可以看到API文档, 并且能够进行在线的操作.

访问 http://127.0.0.1:8080/swagger/v2/api-docs 可以获得生成上述文档的Swagger JSON定义.

访问图片：http://127.0.0.1:8080/swagger/resources/images/111.png

参考资料：

静态资源处理：https://www.cnblogs.com/fangqi/archive/2012/10/28/2743108.html

Spring MVC中Restful API使用 Swagger2 构建 （注意看下面的Swagger-ui.html 404问题）：

http://blog.csdn.net/zhaky/article/details/64906686

swaggerUI页面没有显示api

如图，没有api：



原因：basePackage写错：



修改错误代码：



再次运行成功：