1、添加相关依赖

  1. <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
  2. <dependency>
  3. <groupId>io.springfox</groupId>
  4. <artifactId>springfox-swagger2</artifactId>
  5. <version>2.9.2</version>
  6. </dependency>
  7. <dependency>
  8. <groupId>io.springfox</groupId>
  9. <artifactId>springfox-swagger-ui</artifactId>
  10. <version>2.9.2</version>
  11. </dependency>

2、创建Swagger自动配置类

  1. import org.springframework.context.annotation.Bean;
  2. import org.springframework.context.annotation.Configuration;
  3. import springfox.documentation.builders.ApiInfoBuilder;
  4. import springfox.documentation.builders.PathSelectors;
  5. import springfox.documentation.builders.RequestHandlerSelectors;
  6. import springfox.documentation.service.ApiInfo;
  7. import springfox.documentation.spi.DocumentationType;
  8. import springfox.documentation.spring.web.plugins.Docket;
  9. import springfox.documentation.swagger2.annotations.EnableSwagger2;
  10. @Configuration
  11. @EnableSwagger2
  12. public class Swagger {
  13. @Bean
  14. public Docket createRestApi() {
  15. return new Docket(DocumentationType.SWAGGER_2)
  16. .apiInfo(apiInfo())
  17. .select()
  18. .apis(RequestHandlerSelectors.basePackage("com.ck.demo"))
  19. .paths(PathSelectors.any())
  20. .build();
  21. }
  22. private ApiInfo apiInfo() {
  23. return new ApiInfoBuilder()
  24. .title("Spring Boot中使用Swagger2构建RESTful APIs")
  25. .description("更多Spring Boot相关文章请关注:https://www.yuque.com/chaohen")
  26. .termsOfServiceUrl("https://www.yuque.com/chaohen")
  27. .contact("chaohen")
  28. .version("1.0.0")
  29. .build();
  30. }
  31. }
  • 首先通过@Configuration注解,让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。
  • 其次通过createRestApi函数创建Docket的Bean之后,使用apiInfo()用来创建该Api的基本信息(这些基本信息会展现在文档页面中)。-
  • 再次通过select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现,本例采用指定扫描的包路径来定义,Swagger会扫描该包下所有Controller定义的API,并产生文档内容,这里除了被@ApiIgnore指定的请求。

实际使用:

  1. import com.ck.demo.bean.BlogsUserInfo;
  2. import com.ck.demo.service.UserInfoService;
  3. import io.swagger.annotations.ApiImplicitParam;
  4. import io.swagger.annotations.ApiOperation;
  5. import org.springframework.beans.factory.annotation.Autowired;
  6. import org.springframework.jdbc.core.BeanPropertyRowMapper;
  7. import org.springframework.jdbc.core.JdbcTemplate;
  8. import org.springframework.jdbc.core.RowMapper;
  9. import org.springframework.web.bind.annotation.PathVariable;
  10. import org.springframework.web.bind.annotation.RequestMapping;
  11. import org.springframework.web.bind.annotation.RequestMethod;
  12. import org.springframework.web.bind.annotation.RestController;
  13. import org.springframework.web.context.request.RequestContextHolder;
  14. import org.springframework.web.context.request.ServletRequestAttributes;
  15. import javax.annotation.Resource;
  16. import javax.servlet.http.HttpServletRequest;
  17. import java.util.List;
  18. @RestController
  19. @RequestMapping("user")
  20. public class UsreInfoController {
  21. @Resource
  22. private JdbcTemplate jdbcTemplate;
  23. @Autowired
  24. private UserInfoService userInfoService;
  25. @ApiOperation(value = "获取用户列表",notes = "")
  26. @RequestMapping(value = "/getusers",method = RequestMethod.GET)
  27. public Object getDbType() {
  28. String sql = "select * from blogs_user_info";
  29. RowMapper<BlogsUserInfo> rowMapper = new BeanPropertyRowMapper<BlogsUserInfo>(BlogsUserInfo.class);
  30. List<BlogsUserInfo> list = jdbcTemplate.query(sql, rowMapper);
  31. ServletRequestAttributes servletRequestAttributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
  32. HttpServletRequest request = servletRequestAttributes.getRequest();
  33. Integer times = (Integer) request.getSession().getAttribute("times");
  34. ;
  35. if (times == null) {
  36. times = new Integer(1);
  37. } else {
  38. times = new Integer(times.intValue() + 1);
  39. }
  40. request.getSession().setAttribute("times", times);
  41. System.out.println("***********************" + times);
  42. return list;
  43. }
  44. @ApiOperation(value = "根据用户ID获取用户信息",notes = "")
  45. @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
  46. @RequestMapping("/getId/{id}")
  47. public Object getUserInfoByParmityKey(@PathVariable String id) {
  48. BlogsUserInfo blogsUserInfo = userInfoService.getUserInfoByParmityKeyService(id);
  49. return blogsUserInfo;
  50. }
  51. }

注解语法用例:

  1. @Api:用在请求的类上,表示对类的说明
  2. tags="说明该类的作用,可以在UI界面上看到的注解"
  3. value="该参数没什么意义,在UI界面上也看到,所以不需要配置"
  4. eg: @Api(tags = "用户信息Controller")
  5. @ApiOperation:用在请求的方法上,说明方法的用途、作用
  6. value="说明方法的用途、作用"
  7. notes="方法的备注说明"
  8. eg: @ApiOperation(value="用户登录",notes="手机号、密码都是必填!")
  9. @ApiImplicitParams:用在请求的方法上,表示一组参数说明
  10. @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
  11. name:参数名
  12. value:参数的汉字说明、解释
  13. required:参数是否必须传
  14. paramType:参数放在哪个地方
  15. · header --> 请求参数的获取:@RequestHeader
  16. · query --> 请求参数的获取:@RequestParam
  17. · path(用于restful接口)--> 请求参数的获取:@PathVariable
  18. · body(不常用)
  19. · form(不常用)
  20. dataType:参数类型,默认String,其它值dataType="Integer"
  21. defaultValue:参数的默认值
  22. eg: @ApiImplicitParams({
  23. @ApiImplicitParam(name="username",value="用户名",required=true,paramType="String"),
  24. @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
  25. @ApiImplicitParam(name="vcode",value="验证码",required=true,paramType="form",dataType="Integer")
  26. })
  27. @ApiResponses:用在请求的方法上,表示一组响应
  28. @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
  29. code:数字,例如400
  30. message:信息,例如"请求参数没填好"
  31. response:抛出异常的类
  32. eg@ApiOperation(value = "select1请求",notes = "多个参数,多种的查询参数类型")
  33. @ApiResponses({
  34. @ApiResponse(code=400,message="请求参数没填好"),
  35. @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
  36. })
  37. @ApiModel:用于响应类上,表示一个返回响应数据的信息
  38. (这种一般用在post创建的时候,使用@RequestBody这样的场景,
  39. 请求参数无法使用@ApiImplicitParam注解进行描述的时候)
  40. @ApiModelProperty:用在属性上,描述响应类的属性
  41. eg
  42. import io.swagger.annotations.ApiModel;
  43. import io.swagger.annotations.ApiModelProperty;
  44. import java.io.Serializable;
  45. @ApiModel(description= "返回响应数据")
  46. public class RestMessage implements Serializable{
  47. @ApiModelProperty(value = "是否成功")
  48. private boolean success=true;
  49. @ApiModelProperty(value = "返回对象")
  50. private Object data;
  51. @ApiModelProperty(value = "错误编号")
  52. private Integer errCode;
  53. @ApiModelProperty(value = "错误信息")
  54. private String message;
  55. /* getter/setter */
  56. }

3、在Swagger可视化界面展示

在浏览器输入 http://localhost:8080/user/getusers 结果如下:

  1. {"uuid":"d882f714-c015-4c46-a92e-5d7e2a8b3380","name":"丫丫","age":12,"address":"浙江省","phone":"1898*****63","company":"alibaba"}

在浏览器打开:http://localhost:8080/swagger-ui.html

页面如下:
image.png

详细信息:

get请求

image.png

post请求

image.png

delete请求

image.png

4、详情测试

get请求测试:

image.png

post请求测试

image.png

5、问题解决

问题原因

  1. java.lang.NumberFormatException: For input string: ""
  2. at java.lang.NumberFormatException.forInputString(NumberFormatException.java:65) ~[na:1.8.0_162]
  3. at java.lang.Long.parseLong(Long.java:601) ~[na:1.8.0_162]
  4. at java.lang.Long.valueOf(Long.java:803) ~[na:1.8.0_162]
  5. at io.swagger.models.parameters.AbstractSerializableParameter.getExample(AbstractSerializableParameter.java:412) ~[swagger-models-1.5.20.jar:1.5.20]
  6. at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[na:1.8.0_162]
  7. at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62) ~[na:1.8.0_162]
  8. at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) ~[na:1.8.0_162]
  9. at java.lang.reflect.Method.invoke(Method.java:498) ~[na:1.8.0_162]
  10. at com.fasterxml.jackson.databind.ser.BeanPropertyWriter.serializeAsField(BeanPropertyWriter.java:688) [jackson-databind-2.9.8.jar:2.9.8]
  11. at com.fasterxml.jackson.databind.ser.std.BeanSerializerBase.serializeFields(BeanSerializerBase.java:719) [jackson-databind-2.9.8.jar:2.9.8]
  12. at com.fasterxml.jackson.databind.ser.BeanSerializer.serialize(BeanSerializer.java:155) [jackson-databind-2.9.8.jar:2.9.8]
  13. at com.fasterxml.jackson.databind.ser.impl.IndexedListSerializer.serializeContents(IndexedListSerializer.java:119) [jackson-databind-2.9.8.jar:2.9.8]

项目中使用Swagger作为文档工具,每次打开文档时,控制台都会打印以上异常。

解决办法

这是由于实体类使用@ApiModelProperty时,example属性没有赋值导致的,在AbstractSerializableParameter的getExample方法中会将数值属性的example的转换数值类返回,example的默认值是””,因此当example没有赋值时,会出现上面的异常。getExample方法如下

  1. @JsonProperty("x-example")
  2. public Object getExample() {
  3. if (example == null) {
  4. return null;
  5. }
  6. try {
  7. if (BaseIntegerProperty.TYPE.equals(type)) {
  8. return Long.valueOf(example);
  9. } else if (DecimalProperty.TYPE.equals(type)) {
  10. return Double.valueOf(example);
  11. } else if (BooleanProperty.TYPE.equals(type)) {
  12. if ("true".equalsIgnoreCase(example) || "false".equalsIgnoreCase(defaultValue)) {
  13. return Boolean.valueOf(example);
  14. }
  15. }
  16. } catch (NumberFormatException e) {
  17. LOGGER.warn(String.format("Illegal DefaultValue %s for parameter type %s", defaultValue, type), e);
  18. }
  19. return example;
  20. }

只要将每一个数值类型上@ApiModelProperty的example都赋值数字字符串即可。
但是这个解决方法比较麻烦,若将源码中的if (example == null)改为if (example == null || example.isEmpty())就可以解决问题。我下载并修改了源码,将其打包后覆盖了maven仓库的jar包,这样项目代码不需要任何修改就可以解决问题。
同时,我又查看了v1.5.21的代码 ,源码的修改是一样的。其实也可以排除1.5.20版本的swagger-models.jar,引入1.5.21版本的swagger-models.jar。但是考虑到可能由于代码改动较大引发其他问题,因此个人感觉还是在1.5.20版本代码微调最好。
最后把修复过的jar包下载链接放在这里,下载后替换本地仓库对应的文件,然后项目重新导入jar包即可。
例如,我的电脑,通过命令行进入如下目录
cd /Users/ly/.m2/repository/io/swagger/swagger-models/1.5.20/
然后将两个文件复制进去覆盖原文件。
https://github.com/ly641921791/knowledge/raw/master/swagger/fix-jar/swagger-models-1.5.20.jar
https://github.com/ly641921791/knowledge/raw/master/swagger/fix-jar/swagger-models-1.5.20-sources.jar
此时执行成功,已经达到所需的目标,End。

refer:https://blog.csdn.net/weixin_38229356/article/details/83353347