服务器之家:专注于服务器技术及软件下载分享
分类导航

PHP教程|ASP.NET教程|Java教程|ASP教程|编程技术|正则表达式|C/C++|IOS|C#|Swift|Android|VB|R语言|JavaScript|易语言|vb.net|

服务器之家 - 编程语言 - Java教程 - SpringBoot如何优雅的整合Swagger Api自动生成文档

SpringBoot如何优雅的整合Swagger Api自动生成文档

2021-09-30 01:01kenx Java教程

在多人协作的开发过程中,API文档不仅可以减少等待,也能保证开发的持续进行,这篇文章主要给大家介绍了关于SpringBoot如何优雅的整合Swagger Api自动生成文档的相关资料,需要的朋友可以参考下

前言

一个好的可持续交付的项目,项目说明,和接口文档是必不可少的,swagger api 就可以帮我们很容易自动生成api 文档,不需要单独额外的去写,无侵入式,方便快捷大大减少前后端的沟通方便查找和测试接口提高团队的开发效率方便新人了解项目,剩余的时间就可以去约妹子啦

整合swagger api

这里我们自己去整合swagger api比较麻烦,要导入好几个包,有大神帮我们写好了轮子kinfe4j直接对应SpringBoot的启动项,而且在不影响原来使用功能上界面ui做了美化功能做了增强 我们直接整合这个就好了

  1. <!--api 文档-->
  2. <dependency>
  3. <groupId>com.github.xiaoymin</groupId>
  4. <artifactId>knife4j-spring-boot-starter</artifactId>
  5. <version>3.0.1</version>
  6. </dependency>

正如官网所说

SpringBoot如何优雅的整合Swagger Api自动生成文档

kinfe4j官方文档点击这里

自定义配置信息

为我们为swagger配置更多的接口说明

  1. package cn.soboys.core.config;
  2.  
  3. import cn.hutool.core.collection.CollUtil;
  4. import cn.soboys.core.ret.ResultCode;
  5. import org.springframework.context.annotation.Bean;
  6. import org.springframework.context.annotation.Configuration;
  7. import org.springframework.http.HttpMethod;
  8. import springfox.documentation.builders.ApiInfoBuilder;
  9. import springfox.documentation.builders.PathSelectors;
  10. import springfox.documentation.builders.RequestHandlerSelectors;
  11. import springfox.documentation.builders.ResponseBuilder;
  12. import springfox.documentation.service.ApiInfo;
  13. import springfox.documentation.service.Contact;
  14. import springfox.documentation.service.Response;
  15. import springfox.documentation.spi.DocumentationType;
  16. import springfox.documentation.spring.web.plugins.Docket;
  17.  
  18. import javax.annotation.Resource;
  19. import java.util.Arrays;
  20. import java.util.List;
  21.  
  22. /**
  23. * @author kenx
  24. * @version 1.0
  25. * @date 2021/6/21 16:02
  26. * api 配置类
  27. */
  28. @Configuration
  29. public class SwaggerConfigure {
  30. @Resource
  31. private SwaggerProperty swaggerProperty;
  32.  
  33. /**
  34. * 构造api 文档
  35. * @return
  36. */
  37. @Bean
  38. public Docket createRestApi() {
  39. return new Docket(DocumentationType.OAS_30).globalResponses(HttpMethod.POST, this.responseList()) //全局respons信息
  40. .apiInfo(apiInfo(swaggerProperty)) //文档信息
  41. .select()
  42. //文档扫描
  43. //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //有ApiOperation注解的controller都加入api文档
  44. .apis(RequestHandlerSelectors.basePackage(swaggerProperty.getBasePackage())) //包模式
  45. .paths(PathSelectors.any())
  46. .build();
  47. }
  48.  
  49. private ApiInfo apiInfo(SwaggerProperty swagger) {
  50. return new ApiInfoBuilder()
  51. //标题
  52. .title(swagger.getTitle())
  53. //描述
  54. .description(swagger.getDescription())
  55. //创建联系人信息 (作者,邮箱,网站)
  56. .contact(new Contact(swagger.getAuthor(), swagger.getUrl(), swagger.getEmail()))
  57. //版本
  58. .version(swagger.getVersion())
  59. //认证
  60. .license(swagger.getLicense())
  61. //认证协议
  62. .licenseUrl(swagger.getLicenseUrl())
  63. .build();
  64. }
  65.  
  66. /**
  67. * 全局response 返回信息
  68. * @return
  69. */
  70. private List<Response> responseList() {
  71. List<Response> responseList = CollUtil.newArrayList();
  72. Arrays.stream(ResultCode.values()).forEach(errorEnum -> {
  73. responseList.add(
  74. new ResponseBuilder().code(errorEnum.getCode().toString()).description(errorEnum.getMessage()).build()
  75. );
  76. });
  77. return responseList;
  78. }
  79. }

抽出api文档配置模版信息为属性文件方便复用

  1. package cn.soboys.core.config;
  2.  
  3. import lombok.Data;
  4. import org.springframework.beans.factory.annotation.Value;
  5. import org.springframework.boot.SpringBootConfiguration;
  6.  
  7. /**
  8. * @author kenx
  9. * @version 1.0
  10. * @date 2021/6/21 16:01
  11. * api 文档信息
  12. */
  13. @Data
  14. @SpringBootConfiguration
  15. public class SwaggerProperty {
  16. /**
  17. * 需要生成api文档的 类
  18. */
  19. @Value("${swagger.basePackage}")
  20. private String basePackage;
  21. /**
  22. * api文档 标题
  23. */
  24. @Value("${swagger.title}")
  25. private String title;
  26. /**
  27. * api文档 描述
  28. */
  29. @Value("${swagger.description}")
  30. private String description;
  31. /**
  32. * api文档 版本
  33. */
  34. @Value("${swagger.version}")
  35. private String version;
  36. /**
  37. * api 文档作者
  38. */
  39. @Value("${swagger.author}")
  40. private String author;
  41. /**
  42. * api 文档作者网站
  43. */
  44. @Value("${swagger.url}")
  45. private String url;
  46. /**
  47. * api文档作者邮箱
  48. */
  49. @Value("${swagger.email}")
  50. private String email;
  51. /**
  52. * api 文档 认证协议
  53. */
  54. @Value("${swagger.license}")
  55. private String license;
  56. /**
  57. * api 文档 认证 地址
  58. */
  59. @Value("${swagger.licenseUrl}")
  60. private String licenseUrl;
  61. }

简单使用

在你的Controller上添加swagger注解

  1. @Slf4j
  2. @Api(tags = "登录")
  3. public class LoginController {
  4. private final IUsersService userService;
  5.  
  6. @PostMapping("/login")
  7. @ApiOperation("用户登录")
  8. public String login(@RequestBody UserLoginParams userLoginParams) {
  9. Users u = userService.login(userLoginParams);
  10. return "ok";
  11. }
  12. }

注意如启用了访问权限,还需将swagger相关uri允许匿名访问

  1. /swagger**/**
  2. /webjars/**
  3. /v3/**
  4. /doc.html

重启服务,自带api文档访问链接为/doc.html界面如下:

SpringBoot如何优雅的整合Swagger Api自动生成文档

相比较原来界面UI更加漂亮了,信息更完善功能更强大

Swagger常用注解

SpringBoot如何优雅的整合Swagger Api自动生成文档

Api标记

用在请求的类上,表示对类的说明,也代表了这个类是swagger2的资源

参数:

  • tags:说明该类的作用,参数是个数组,可以填多个。
  • value="该参数没什么意义,在UI界面上不显示,所以不用配置"
  • description = "用户基本信息操作"

ApiOperation标记

用于请求的方法上表示一个http请求的操作

参数:

  • value用于方法描述
  • notes用于提示内容
  • tags可以重新分组(视情况而用)

ApiParam标记

用于请求方法上对请求参数,字段说明;表示对参数的添加元数据(说明或是否必填等)

参数:

  • name–参数名
  • value–参数说明
  • required–是否必填

ApiModel标记

用于java实体类上表示对类进行说明,用于参数用实体类接收

参数:

  • value–表示对象名
  • description–描述
    都可省略

ApiModelProperty标记

用于方法,字段; 表示对model属性的说明或者数据操作更改

参数:

  1. value–字段说明
  2. name–重写属性名字
  3. dataType–重写属性类型
  4. required–是否必填
  5. example–举例说明
  6. hidden–隐藏
  1. @ApiModel(value="user对象",description="用户对象user")
  2. public class User implements Serializable{
  3. private static final long serialVersionUID = 1L;
  4. @ApiModelProperty(value="用户名",name="username",example="xingguo")
  5. private String username;
  6. @ApiModelProperty(value="状态",name="state",required=true)
  7. private Integer state;
  8. private String password;
  9. private String nickName;
  10. private Integer isDeleted;
  11.  
  12. @ApiModelProperty(value="id数组",hidden=true)
  13. private String[] ids;
  14. private List<String> idList;
  15. //省略get/set
  16. }

ApiIgnore标记

用于请求类或者方法上,可以不被swagger显示在页面上

ApiImplicitParam标记

用于方法表示单独的请求参数

ApiImplicitParams标记

用于方法,包含多个 @ApiImplicitParam

参数:

  1. name–参数名
  2. value–参数说明
  3. dataType–数据类型
  4. paramType–参数类型
  5. example–举例说明
  1. @ApiOperation("查询测试")
  2. @GetMapping("select")
  3. //@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query")
  4. @ApiImplicitParams({
  5. @ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"),
  6. @ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")})
  7. public void select(){
  8.  
  9. }

总结

  • 可以给实体类和接口添加注释信息
  • 接口文档实时更新
  • 在线测试
  • kinfe4j 在swagger API只做增强,不会改变原有任何使用,更多增加使用功能

点击这里进入kinfe4j官网文档

到此这篇关于SpringBoot如何优雅的整合Swagger Api自动生成文档的文章就介绍到这了,更多相关SpringBoot整合Swagger Api内容请搜索服务器之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持服务器之家!

原文链接:https://www.cnblogs.com/kenx/p/14984816.html

延伸 · 阅读

精彩推荐
  • Java教程Java使用SAX解析xml的示例

    Java使用SAX解析xml的示例

    这篇文章主要介绍了Java使用SAX解析xml的示例,帮助大家更好的理解和学习使用Java,感兴趣的朋友可以了解下...

    大行者10067412021-08-30
  • Java教程升级IDEA后Lombok不能使用的解决方法

    升级IDEA后Lombok不能使用的解决方法

    最近看到提示IDEA提示升级,寻思已经有好久没有升过级了。升级完毕重启之后,突然发现好多错误,本文就来介绍一下如何解决,感兴趣的可以了解一下...

    程序猿DD9332021-10-08
  • Java教程xml与Java对象的转换详解

    xml与Java对象的转换详解

    这篇文章主要介绍了xml与Java对象的转换详解的相关资料,需要的朋友可以参考下...

    Java教程网2942020-09-17
  • Java教程20个非常实用的Java程序代码片段

    20个非常实用的Java程序代码片段

    这篇文章主要为大家分享了20个非常实用的Java程序片段,对java开发项目有所帮助,感兴趣的小伙伴们可以参考一下 ...

    lijiao5352020-04-06
  • Java教程Java8中Stream使用的一个注意事项

    Java8中Stream使用的一个注意事项

    最近在工作中发现了对于集合操作转换的神器,java8新特性 stream,但在使用中遇到了一个非常重要的注意点,所以这篇文章主要给大家介绍了关于Java8中S...

    阿杜7472021-02-04
  • Java教程小米推送Java代码

    小米推送Java代码

    今天小编就为大家分享一篇关于小米推送Java代码,小编觉得内容挺不错的,现在分享给大家,具有很好的参考价值,需要的朋友一起跟随小编来看看吧...

    富贵稳中求8032021-07-12
  • Java教程Java实现抢红包功能

    Java实现抢红包功能

    这篇文章主要为大家详细介绍了Java实现抢红包功能,采用多线程模拟多人同时抢红包,文中示例代码介绍的非常详细,具有一定的参考价值,感兴趣的小伙...

    littleschemer13532021-05-16
  • Java教程Java BufferWriter写文件写不进去或缺失数据的解决

    Java BufferWriter写文件写不进去或缺失数据的解决

    这篇文章主要介绍了Java BufferWriter写文件写不进去或缺失数据的解决方案,具有很好的参考价值,希望对大家有所帮助。如有错误或未考虑完全的地方,望...

    spcoder14552021-10-18