当前位置:   article > 正文

knife4j文档请求异常_Spring Boot优雅整合Swagger2,自动生成在线文档

knife4j-spring-boot-starter 请求不到

656bd9e0654c36747d1f7b13ee20794a.png

Spring Boot优雅整合Swagger2,自动生成在线文档

日常求赞,感谢老板。
欢迎关注公众号:其实是白羊。干货持续更新中......

一、前言

现在的很多项目都是前后端分离的,后端提供接口,前端调用接口,在这个过程中一般后端会向前端提供一份接口文档,但是随着程序的调整,我们还要不断的去迭代接口文档,最后可能会搞出一堆,写起来比较耗时且在规范性上也很难要求。在这个前提下我们可以选择Swagger加入到我们的项目中。

Swagger提供了很多的功能,其中Swagger UI和Swagger Inspector使用的比较多

  • Swagger UI:提供了一个UI页面描述项目中的接口(包括接口含义、uri、方法、参数、返回值和字段含义等)
  • Swagger Inspector:提供了在线对接口进行测试的功能

二、集成Swagger

我们这里的项目框架是Spring Boot

1.引入依赖

  1. <dependency>
  2. <groupId>io.springfox</groupId>
  3. <artifactId>springfox-swagger2</artifactId>
  4. <version>2.9.2</version>
  5. </dependency>
  6. <dependency>
  7. <groupId>io.springfox</groupId>
  8. <artifactId>springfox-swagger-ui</artifactId>
  9. <version>2.9.2</version>
  10. </dependency>

2.配置类

  1. /**
  2. * @Description swagger配置文件
  3. * @Author ZhangLinlu
  4. * @Date 2020/10/10
  5. **/
  6. @EnableSwagger2
  7. @Configuration
  8. public class SwaggerConfig {
  9. private ApiInfo apiInfo() {
  10. return new ApiInfoBuilder()
  11. // 设置页面标题
  12. .title("使用swagger2构建后端api接口文档")
  13. // 设置联系人
  14. .contact(new Contact("myname", "url", "email"))
  15. // 描述
  16. .description("欢迎访问后端接口文档,这里是描述信息")
  17. // 定义版本号
  18. .version("1.0").build();
  19. }
  20. @Bean
  21. public Docket createRestApi() {
  22. return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
  23. //接口所在的包
  24. .apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo.controller"))
  25. .paths(PathSelectors.any()).build();
  26. }
  27. }

至此,我们就可以访问http://localhost:8080/swagger-ui.html看到swagger为我们提供的在线调试和在线接口文档的页面了

efacf54048c31569c63e9acb08aefbf5.png

但是,目前上面的描述信息还不够详细。我们可以通过下面的注解来完善对接口、参数、返回值等的描述

3.常用注解

ble data-draft-node="block" data-draft-type="table" data-size="normal" data-row-style="normal">

附3.1:

  • name="参数"
  • value="参数含义描述"
  • required=true/false是否必传
  • paramType="参数位置"
    • header:参数在请求头,通过@RequestHeader获取
    • query:参数通过@RequestParam获取
    • path:参数在restfull接口url上,通过@PathVariable获取
  • dataType="参数类型,如String等"
  • defaultValue="参数默认值"

举个栗子:

  1. /**
  2. * @Description 测试接口
  3. * @Author ZhangLinlu
  4. * @Date 2020/10/10
  5. **/
  6. @Api(tags = "测试接口")
  7. @RestController
  8. public class TestController {
  9. @ApiOperation(value = "我是test1接口",notes = "notes:我是test1")
  10. @ApiImplicitParams(value = {
  11. @ApiImplicitParam(name = "name",value = "姓名",required = true,paramType = "query",dataType = "String",defaultValue = "zll")
  12. })
  13. @GetMapping("test1")
  14. public Object test1(String name) {
  15. return "success" + name;
  16. }
  17. @ApiOperation(value = "我是test2接口",notes = "notes:我是test2")
  18. @GetMapping("test2")
  19. public Object test2(TestParamDTO testParamDTO) {
  20. return "success" + testParamDTO.getName();
  21. }
  22. }
  23. /**
  24. * @Description 测试javabean参数
  25. * @Author ZhangLinlu
  26. * @Date 2020/10/10
  27. **/
  28. @Data
  29. @ApiModel(value = "测试javabean参数")
  30. public class TestParamDTO {
  31. @ApiModelProperty(name = "name",value = "姓名",required = true)
  32. private String name;
  33. }

80cc5f3b5623147ba9901a65ef358739.png

dcbec1f9aa3cd5b5f9f5dd594cc65a2f.png

f81f8198102d97570648b01752c03c7c.png

到这里已经完成了整个的整合,前端再让你出接口文档,直接url地址扔给她,潇洒转身离开。程序改动也不用重新写一份,改了哪里注解改一下就行了。

4.“你这页面好丑啊”

“你这页面好丑啊,接口多了也不好找。。。。”

“线上调试,接口做了鉴权没token怎么办。。。。”

面对这些吐槽,下面介绍一个好看的ui:knife4j(https://gitee.com/xiaoym/knife4j),这是个人维护的ui项目很好的解决了上面的问题

引入knife4j只需要引入相应的依赖,其他的都不用修改,完美兼容

  1. <dependency>
  2. <groupId>com.github.xiaoymin</groupId>
  3. <artifactId>knife4j-spring-boot-starter</artifactId>
  4. <version>2.0.2</version>
  5. </dependency>

可以把之前引入的swagger依赖都去掉了,这个依赖包含了所需的swagger依赖

这次访问线上接口文档的地址改成了:http://localhost:8080/doc.html

136d816d82ba0933ba21a4cab1319aed.png

不仅优化了ui界面,而且在文档管理中为我们提供了全局参数、离线文档等功能,很值得推荐。

三、最后

文章中的demo我已经上传到了gitee,需要的可以clone看一下:https://gitee.com/zhanglinlu/swagger-demo

点个赞啊亲

如果你认为本文对你有帮助,可以「在看/转发/赞/star」,多谢 如果你还发现了更好或不同的想法,还可以在留言区一起探讨下

欢迎关注公众号:「其实是白羊」干货持续更新中......

e5fff6fe8c7320c608226c30a4b17ad1.png
声明:本文内容由网友自发贡献,不代表【wpsshop博客】立场,版权归原作者所有,本站不承担相应法律责任。如您发现有侵权的内容,请联系我们。转载请注明出处:https://www.wpsshop.cn/w/神奇cpp/article/detail/891302
推荐阅读
相关标签
  

闽ICP备14008679号