项目接口越来越多,文档维护也是比较麻烦,所以接口包准备集成Swagger2,在线API!我用的是maven,所以直接写maven的方案了!
一、具体步骤:
1.1、pom.xml,引入springfox-swagger2和springfox-swagger-ui架包:
<!-- swagger2核心依赖 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<!-- swagger-ui为项目提供api展示及测试的界面 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
1.2、配置SwaggerConfig.java
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @author <a href="934804229">934804229</a>
* @version 2019/8/19 17:23
* @description SwaggerConfig2
*/
@Configuration
@EnableWebMvc
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
//.apis(RequestHandlerSelectors.any()) //显示所有类
//.apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) //只显示添加@Api注解的类
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))//只显示添加@ApiOperation注解的接口
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("开放接口API") //粗标题
.description("HTTP对外开放接口") //描述
.version("1.0.0") //api version
.termsOfServiceUrl("http://IP:PORT/OBJ-NAME/swagger-ui.html")
// .license("LICENSE") //链接名称
// .licenseUrl("http://xxx.xxx.com") //链接地址
.build();
}
}
1.3、配置spring-servlet.xml
<!-- swagger静态资源访问配置 -->
<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" />
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/" />
<bean class="cn.**.**.**.common.SwaggerConfig"/>
1.4、接口类注解配置配置
@Controller
@RequestMapping(value = "/api")
@Api(value = "emsModel", description = "快递查询模块", produces = MediaType.APPLICATION_JSON_VALUE)
public class EmsController {
@ResponseBody
@RequestMapping(value = "/v2/emsModel/emsQuery")
@ApiOperation(value = "EMS查询接口v2版", httpMethod = "POST", response = ResponseMainEntity.class, notes = "EMS查询接口v2版")
public ResponseMainEntity<HashMap> emsQuery(@RequestBody RequestMainEntity requestData) {
ResponseMainEntity responseMainEntity = new ResponseMainEntity();
responseMainEntity = emsQueryV1(requestData);
return responseMainEntity;
}
}
注:如果是实体接受,需要采用@RequestBody注解去注释实体。
1.5、Swagger访问路径:
http://IP:PORT/项目名称/swagger-ui.html
效果图如下:
1.6、swagger注解含义见下面第三项
二、报错解决方案
2.1、如果报:swagger-ui.min.js:8 Uncaught TypeError: Cannot read property 'definitions' of null
解决方案:检查是否引入fastjson架包,如果是,检查其版本是不是1.2以下的版本,swagger2好像对1.2以下的fastjson版本不支持,升级至1.2以上再试试!
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>fastjson</artifactId>
<version>1.2.30</version>
</dependency>
三、swagger2注解含义
以下是swagger2注解中的全参数,有兴趣可以都试试
@Api
Api 标记可以标记一个Controller类做为swagger 文档资源,使用方式
属性名称 | 备注 |
value | url的路径值 |
tags | 如果设置这个值、value的值会被覆盖 |
description | 对api资源的描述 |
basePath | 基本路径可以不配置 |
position | 如果配置多个Api 想改变显示的顺序位置 |
produces | For example, “application/json, application/xml” |
consumes | For example, “application/json, application/xml“ |
protocols | Possible values: http, https, ws, wss. |
authorizations | 高级特性认证时配置 |
hidden | 配置为true 将在文档中隐藏 |
@ApiOperation每一个url资源的定义,使用方式
属性名称 | 备注 |
value | url的路径值 |
tags | 如果设置这个值、value的值会被覆盖 |
description | 对api资源的描述 |
basePath | 基本路径可以不配置 |
position | 如果配置多个Api 想改变显示的顺序位置 |
produces | For example, “application/json, application/xml |
consumes | For example, “application/json, application/xml |
protocols | Possible values: http, https, ws, wss. |
authorizations | 高级特性认证时配置 |
hidden | 配置为true 将在文档中隐藏 |
response | 返回的对象 |
responseContainer | 这些对象是有效的 “List”, “Set” or “Map”.,其他无效 |
httpMethod | “GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH |
code | http的状态码 默认 200 |
extensions | 扩展属性 |
@ApiParam标记
public ResponseEntity createUser(@RequestBody @ApiParam(value = “user”, required = true) User user)
属性名称 | 备注 |
name | 属性名称 |
value | 属性值 |
defaultValue | 默认属性值 |
allowableValues | 可以不配置 |
required | 是否属性必填 |
access | 不过多描述 |
allowMultiple | 默认为false |
hidden | 隐藏该属性 |
example | 举例子 |
@ApiImplicitParam对容器的描述
属性名称 | 备注 |
name | 属性名称 |
value | 属性值 |
defaultValue | 默认值 |
allowableValues | 可以不可配置 |
required | 是否属性必填 |
access | 不可过多描述 |
allowMutiple | 默认为false |
dataType | 数据类型 |
paramType | 参数类型 |
@ApiResponse
属性名称 | 备注 |
code | http的状态码 |
message | 描述 |
response | 默认响应类 Void |
reference | 参考ApiOperation中配置 |
responseHeaders | 参考 ResponseHeader 属性配置说明 |
responseContainer | 参考ApiOperation中配置 |
参数解释的原文链接:https://blog.csdn.net/qq_36911145/article/details/82854417