SpringMVC集成Swagger2生成在线API文档及其报错解决方案

项目接口越来越多，文档维护也是比较麻烦，所以接口包准备集成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

Tastill

发布了57 篇原创文章 · 获赞 44 · 访问量 16万+

私信关注

SpringMVC集成Swagger2生成在线API文档及其报错解决方案

猜你喜欢