springboot-swagger报错

一、具体步骤:

1.1、pom.xml,引入springfox-swagger2和springfox-swagger-ui架包:


<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


<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

推荐阅读更多精彩内容