Swagger概述
- swagger对Spring或者Springboot项目中所暴露的Restful接口,提供自动化网页文档生成插件
- 可以在swagger中对restful接口进行模拟调用
Swgger的环境的配置
Swagger所需的jar包特别多,一定要通过Maven等jar包管理插件去下载依赖包,不要自己找
前置条件
- 创建maven项目以便对所需jar包进行统一管理
- 项目中已经集成Spring以便进行反转控制
- 在配置web.xml的spring-filtter时,要开放所有过滤后缀请求
<servlet>
<servlet-name>springmvc</servlet-name>
<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
<!-- 保证SpringMVC能够正确找到Spring配置文件 -->
<init-param>
<param-name>contextConfigLocation</param-name>
<param-value>classpath*:/applicationContext.xml</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>springmvc</servlet-name>
<!-- 不单是.do请求,而是所有请求 -->
<url-pattern>/</url-pattern>
</servlet-mapping>
下载依赖包
maven中需要指定的jar包只有如下两个,但mavne会自动下载配套的10多个jar包
注意:
- 一定是io.springfox组下的swagger包,而不是其他组的swagger
- 版本不宜过高,2.7或2.8即可,过高版本容易出现一些不可预期的问题
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
配置swagger的参数文件
- 一般可以在项目的任意包下创建一个SwaggerConfing.java(名称自定)文件用于设置Swagger参数
- 因为配置了Spring/Springboot,因此将该配置类的实例化和调用过程交由Spring进行实现
- 配置类建议实现
WebMvcConfigurerAdapter
接口,以便对swagger的jar包中的静态资源文件进行网络请求放行
具体代码如下所示
package com.geoq.framework.swagger;
//以下三个注解都必须加上
@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig extends WebMvcConfigurerAdapter
{
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.geoq")) //swagger只搜索特定包下的所有Swagger支持的注解
//.apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) //只显示添加@Api注解的类
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("项目功能开发接口") //页面住标题
.description("HTTP对外开放接口") //页面描述标题
.version("1.0.0") //api version
.build();
}
//对swagger包中的静态资源进行放行,否则容易出现访问安全异常,或空白页面
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
确保Spring工厂可以管理到这个类
以自动扫描为例
<context:component-scan base-package="com.geoq.framework"></context:component-scan>
Swagger的基本注解
基本注解表
标签名 | 功能说明 | 作用点 |
---|---|---|
@Api | 标识当前类被Swagger扫描管理 | Controller类 |
@ApiOperation() | 标识当前方法被Swagger扫描管理 | Controller 的方法 |
@ApiParam | 标识当前函数参数被Swagger扫描管理 | Controller方法的参数 |
@ApiModel() | 标识当前类是请求/响应数据传输实体 | VO类 |
@ApiModelProperty | 标识当前类是请求/响应数据传输实体的属性 | VO类属性 |
使用实例
@RestController /*Spring的注解*/
@RequestMapping("/demo") /*Spring的注解*/
@Api(value = "/ProductController", tags = "接口开放示例") /*Swagger的注解,标识一个API分组*/
public class DemoController
{
@Autowired
private DemoService service;
/*Spring的注解*/
@RequestMapping(value = "/HelloWorld.do", method = RequestMethod.POST)
/*Swagger的注解,标识一个Restful请求接口*/
@ApiOperation(value = "网络通讯测试", notes = "网络通讯测试", httpMethod = "POST", response = BaseDataMessage.class)
public ResponseEntity<BaseDataMessage> HelloWorld(HttpServletRequest request)
{
BaseDataMessage dataMessage = new BaseDataMessage();
int status = service.HelloWorld(request, dataMessage);
return ResponseEntity.status(status).body(dataMessage);
}
}
运行结果与问题排错
正常运行
在浏览器地址栏中输入host:port/projectname/swagger-ui.html,即可在页面中弹出如下页面
网页自身404
- Spring集成错误,
- Spring没有正确扫描到Swagger配置类所在包
- Swagger配置类的注解不全
网页仅有Swagger工具条,没有Restful接口条目
- 检查静态资源访问没有被正确放行,检查配置类的addResourceHandlers函数是否已经添加
- Spring没有开启所有请求后缀的过滤,只放行了.do等特殊请求后缀
安全验证错误
- Swagger版本过高或者与其他jar包有冲突
- 不是下载的io.springfox组下的swagger包
- 检查静态资源访问没有被正确放行,检查配置类的addResourceHandlers函数是否已经添加
- Spring没有开启所有请求后缀的过滤,只放行了.do等特殊请求后缀