环境说明
spring boot: 1.5.16.RELEASE
swagger2: 2.2.0
jdk:1.8 _152
spring boot 集成 swagger2
添加Swagger2依赖
在pom.xml
中加入Swagger2的依赖
1 | <dependency> |
创建Swagger2配置类
在Application.java
同级创建Swagger2的配置类Swagger2
。
1 | package com.linezone.biwork; |
添加文档内容
1 | import com.linezone.biwork.web.model.User; |
完成上述代码添加上,启动Spring Boot程序,访问:http://localhost:port/swagger-ui.html
。就能看到前文所展示的RESTful API的页面。我们可以再点开具体的API请求,以POST类型的/users请求为例,可找到上述代码中我们配置的Notes信息以及参数user的描述信息,如下图所示。
swagger2注解说明
介绍
swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。
- @Api()用于类;
表示标识这个类是swagger的资源 - @ApiOperation()用于方法;
表示一个http请求的操作 - @ApiParam()用于方法,参数,字段说明;
表示对参数的添加元数据(说明或是否必填等) - @ApiModel()用于类
表示对类进行说明,用于参数用实体类接收 - @ApiModelProperty()用于方法,字段
表示对model属性的说明或者数据操作更改 - @ApiIgnore()用于类,方法,方法参数
表示这个方法或者类被忽略 - @ApiImplicitParam() 用于方法
表示单独的请求参数 - @ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam
详细介绍
@Api()
用于类;表示标识这个类是swagger的资源
tags–表示说明
value–也是说明,可以使用tags替代
但是tags如果有多个值,会生成多个list
@ApiOperation() 用于方法;表示一个http请求的操作
value用于方法描述
notes用于提示内容
tags可以重新分组(视情况而用)
@ApiParam() 用于方法,参数,字段说明;表示对参数的添加元数据(说明或是否必填等)
name–参数名
value–参数说明
required–是否必填
@ApiModel()用于类 ;表示对类进行说明,用于参数用实体类接收
value–表示对象名
description–描述
都可省略
@ApiModelProperty()用于方法,字段; 表示对model属性的说明或者数据操作更改
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏
@ApiIgnore()用于类或者方法上,可以不被swagger显示在页面上
比较简单, 这里不做举例
@ApiImplicitParam() 用于方法
表示单独的请求参数
@ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam
name–参数ming
value–参数说明
dataType–数据类型
paramType–参数类型
example–举例说明
swagger2集成问题
问题描述:
1 | "获取用户详细信息", notes="根据url的id来获取用户详细信息") (value= |
2018-10-10 13:49:54.478 WARN 2072 — [io-3333-exec-10] .w.s.m.s.DefaultHandlerExceptionResolver : Resolved [org.springframework.web.method.annotation.MethodArgumentTypeMismatchException: Failed to convert value of type ‘java.lang.String’ to required type ‘java.lang.Long’; nested exception is java.lang.NumberFormatException: For input string: “{id}”]
解决办法
如果上诉代码没有写paramType = “path”
会提示类型转换String convert to Long
错误。