java集成开发SpringBoot生成接口文档示例实现

目录
  • 为什么要用Swagger ?
  • Swagger集成
    • 第一步: 引入依赖包
    • 第二步:修改配置文件
    • 第三步,配置API接口
  • Unable to infer base url
  • For input string: “”
  • Swagger美化
    • 第一步: 引入依赖包
    • 第二步:启用knife4j增强
  • Swagger参数分组
  • 分组使用说明
    • 1.在bean对象的属性里配置如下注释
    • 2.在接口参数的时候加入组规则校验
  • 小结

大家好,我是飘渺。

SpringBoot老鸟系列的文章已经写了两篇,每篇的阅读反响都还不错,果然大家还是对SpringBoot比较感兴趣。那今天我们就带来老鸟系列的第三篇:集成Swagger接口文档以及Swagger的高级功能。 文章涉及到的代码已经上传到了github,希望最终能应用在你们实际项目上,当然如果有其他需要我添加到内容也可以直接留言告诉我,我会视情况给你们加上去的。

SpringBoot 如何统一后端返回格式?老鸟们都是这样玩的!

SpringBoot 如何进行参数校验?老鸟们都是这样玩的!

好了,闲话少叙,让我们先来看看为什么要用Swagger?

为什么要用Swagger ?

作为一名程序员,我们最讨厌两件事:1. 别人不写注释。2. 自己写注释。

而作为一名接口开发者,我们同样讨厌两件事:

1. 别人不写接口文档,文档不及时更新。

2. 需要自己写接口文档,还需要及时更新。

相信无论是前端还是后端开发,都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新。

而随着Springboot、Springcloud等微服务的流行,每个项目都有成百上千个接口调用,这时候再要求人工编写接口文档并且保证文档的实时更新几乎是一件不可能完成的事,所以这时候我们迫切需要一个工具,一个能帮我们自动化生成接口文档以及自动更新文档的工具。它就是Swagger。

Swagger 提供了一个全新的维护 API 文档的方式,有4大优点:

自动生成文档:只需要少量的注解,Swagger 就可以根据代码自动生成 API 文档,很好的保证了文档的时效性。

跨语言性,支持 40 多种语言。

Swagger UI 呈现出来的是一份可交互式的 API 文档,我们可以直接在文档页面尝试 API 的调用,省去了准备复杂的调用参数的过程。

还可以将文档规范导入相关的工具(例如 SoapUI), 这些工具将会为我们自动地创建自动化测试。

现在我们知道了Swagger的作用,接下来将其集成到我们项目中。

Swagger集成

集成Swagger很简单,只需要简单三步。

第一步: 引入依赖包

<!--swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!--swagger-ui-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

第二步:修改配置文件

application.properties 加入配置

# 用于控制是否开启Swagger,生产环境记得关闭Swagger,将值设置为 false
springfox.swagger2.enabled = true

增加一个swagger配置类

@Configuration
@EnableSwagger2
@ConditionalOnClass(Docket.class)
public class SwaggerConfig {

    private static final String VERSION = "1.0";

    @Value("${springfox.swagger2.enabled}")
    private Boolean swaggerEnabled;

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(swaggerEnabled)
                .groupName("SwaggerDemo")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 添加摘要信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档")
                .contact(new Contact("JAVA日知录","http://javadaily.cn","jianzh5@163.com"))
                .description("Swagger接口文档")
                .version(VERSION)
                .build();
    }

}

这里通过 .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))

表面给加上 @Api注解的类自动生成接口文档。

第三步,配置API接口

@RestController
@Api(tags = "参数校验")
@Slf4j
@Validated
public class ValidController {

    @PostMapping("/valid/test1")
    @ApiOperation("RequestBody校验")
    public String test1(@Validated @RequestBody ValidVO validVO){
        log.info("validEntity is {}", validVO);
        return "test1 valid success";
    }

    @ApiOperation("Form校验")
    @PostMapping(value = "/valid/test2")
    public String test2(@Validated ValidVO validVO){
        log.info("validEntity is {}", validVO);
        return "test2 valid success";
    }

    @ApiOperation("单参数校验")
    @PostMapping(value = "/valid/test3")
    public String test3(@Email String email){
        log.info("email is {}", email);
        return "email valid success";
    }
}

通过 @Api注解标注需要生成接口文档,通过 @ApiOperation注解标注接口名。

同时我们给 ValidVO也加上对应的注解

@Data
@ApiModel(value = "参数校验类")
public class ValidVO {

    @ApiModelProperty("ID")
    private String id;

    @ApiModelProperty(value = "应用ID",example = "cloud")
    private String appId;

    @NotEmpty(message = "级别不能为空")
    @ApiModelProperty(value = "级别")
    private String level;

    @ApiModelProperty(value = "年龄")
    private int age;

    ...

}

通过 @ApiModel标注这是一个参数实体,通过 @ApiModelProperty标注字段说明。

Unable to infer base url

简单三步,我们项目就集成了Swagger接口文档,赶紧启动服务,访问 http://localhost:8080/swagger-ui.html 体验一下。

好吧,出了点小问题,不过不用慌。

出现这个问题的原因是因为我们加上了 ResponseBodyAdvice统一处理返回值/响应体,导致给Swagger的返回值也包装了一层,UI页面无法解析。可以通过 http://localhost:8080/v2/api-docs?group=SwaggerDemo观察Swagger返回的json数据。

既然知道了问题原因那就很好解决了,我们只需要在ResponseBodyAdvice处理类中只转换我们自己项目的接口即可。

@RestControllerAdvice(basePackages = "com.jianzh5.blog")
@Slf4j
public class ResponseAdvice implements ResponseBodyAdvice<Object> {
  ...
}

通过添加basePackage属性限定统一返回值的范围,这样就不影响Swagger了。

重启服务器再次访问swagger接口地址,就可以看到接口文档页面了。

For input string: “”

Swagger2.9.2有个bug,就是当我们参数实体有int类型的参数时,打开Swagger接口页面时后端会一直提示异常:

java.lang.NumberFormatException: For input string: ""
	at java.base/java.lang.NumberFormatException.forInputString(NumberFormatException.java:65)
	at java.base/java.lang.Long.parseLong(Long.java:702)
	at java.base/java.lang.Long.valueOf(Long.java:1144)

有两种解决方案:

给int类型的字段使用@ApiModelPorperty注解时添加example属性

@ApiModelProperty(value = "年龄",example = "10")
private int age;

去除原swagger中的swagger-modelsswagger-annotations,自行引入高版本的annotations和models

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
  <exclusions>
    <exclusion>
      <groupId>io.swagger</groupId>
      <artifactId>swagger-annotations</artifactId>
    </exclusion>
    <exclusion>
      <groupId>io.swagger</groupId>
      <artifactId>swagger-models</artifactId>
    </exclusion>
  </exclusions>
</dependency>

<dependency>
  <groupId>io.swagger</groupId>
  <artifactId>swagger-annotations</artifactId>
  <version>1.5.22</version>
</dependency>
<dependency>
  <groupId>io.swagger</groupId>
  <artifactId>swagger-models</artifactId>
  <version>1.5.22</version>
</dependency>

集成Swagger过程中虽然会出现两个小问题,解决后我们就可以愉快享受Swagger给我们带来的便利了。

Swagger美化

Swagger原生UI有点丑,我们可以借助Swagger的增强工具 knife4j优化一下。

第一步: 引入依赖包

 <!--整合Knife4j-->
<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-boot-starter</artifactId>
  <version>2.0.4</version>
</dependency>

由于knife4j中已经带了 swagger-annotations和 swagger-models的依赖,所以我们可以把上文中手动添加的两个依赖删除。

第二步:启用knife4j增强

@Configuration
@EnableSwagger2
@ConditionalOnClass(Docket.class)
@EnableKnife4j
public class SwaggerConfig {
  ...
}

通过上面两步我们就完成了Swagger的美化,通过浏览器访问 http://localhost:8080/doc.html 即可看到效果。

Swagger参数分组

看到这里的同学心理肯定会想,就这?这就是老鸟的做法?跟我们新手也没啥区别呀

别急,我们先来看一个效果。

首先我们定义了两个接口,一个新增,一个编辑

@ApiOperation("新增")
@PostMapping(value = "/valid/add")
public String add(@Validated(value = {ValidGroup.Crud.Create.class}) ValidVO validVO){
  log.info("validEntity is {}", validVO);
  return "test3 valid success";
}

@ApiOperation("更新")
@PostMapping(value = "/valid/update")
public String update(@Validated(value = ValidGroup.Crud.Update.class) ValidVO validVO){
  log.info("validEntity is {}", validVO);
  return "test4 valid success";
}

注意看,这里用的是同一个实体 ValidVO来接收前端参数,只不过使用了参数校验中的分组,然后我们打开kife4j页面观察两者的接口文档有何不同。

新增:

编辑:

通过上面可以看到,虽然用于接受参数的实体一样,但是当分组不一样时展示给前端的参数也不一样,这就是Swagger的分组功能。

当然原生的Swagger是不支持分组功能的,我们需要对Swagger进行扩展。我已经将代码上传到了github上,由于代码量比较多这里就不展示了,大家可以自行查阅。

引入扩展类后还需要在Swagger配置类 SwaggerConfig中注入对应的Bean。

@Configuration
@EnableSwagger2
@ConditionalOnClass(Docket.class)
@EnableKnife4j
public class SwaggerConfig {
    ...

    @Bean
    @Order(SwaggerPluginSupport.SWAGGER_PLUGIN_ORDER + 1000)
    public GroupOperationModelsProviderPlugin groupOperationModelsProviderPlugin() {
        return new GroupOperationModelsProviderPlugin();
    }

    @Bean
    @Order(SwaggerPluginSupport.SWAGGER_PLUGIN_ORDER + 1000)
    public GroupModelBuilderPlugin groupModelBuilderPlugin() {
        return new GroupModelBuilderPlugin();
    }

    @Bean
    @Order(SwaggerPluginSupport.SWAGGER_PLUGIN_ORDER + 1000)
    public GroupModelPropertyBuilderPlugin groupModelPropertyBuilderPlugin() {
        return new GroupModelPropertyBuilderPlugin();
    }

    @Bean
    @Order(SwaggerPluginSupport.SWAGGER_PLUGIN_ORDER + 1000)
    public GroupExpandedParameterBuilderPlugin groupExpandedParameterBuilderPlugin() {
        return new GroupExpandedParameterBuilderPlugin();
    }

    @Bean
    @Order(SwaggerPluginSupport.SWAGGER_PLUGIN_ORDER + 1000)
    public GroupOperationBuilderPlugin groupOperationBuilderPlugin() {
        return new GroupOperationBuilderPlugin();
    }

    @Bean
    @Primary
    @Order(SwaggerPluginSupport.SWAGGER_PLUGIN_ORDER + 1000)
    public GroupModelAttributeParameterExpander groupModelAttributeParameterExpander(FieldProvider fields, AccessorsProvider accessors, EnumTypeDeterminer enumTypeDeterminer) {
        return new GroupModelAttributeParameterExpander(fields, accessors, enumTypeDeterminer);
    }

}

分组使用说明

1.在bean对象的属性里配置如下注释

@Null(groups = ValidGroup.Crud.Create.class)
@NotNull(groups = ValidGroup.Crud.Update.class,message = "应用ID不能为空")
@ApiModelProperty(value = "应用ID",example = "cloud")
private String appId;

当新增场景的时候,appId为空,不需要传值; 当修改场景的时候,appId不能为空,需要传值 ;其他没有配置组的皆为默认组(Default)

2.在接口参数的时候加入组规则校验

 @ApiOperation("新增")
 @PostMapping(value = "/valid/add")
 public String add(@Validated(value = {ValidGroup.Crud.Create.class}) ValidVO validVO){
 	log.info("validEntity is {}", validVO);
 	return "test3 valid success";
 }

当前接口会针对默认组的bean属性进行校验,同时针对保存常见的属性进行校验。

小结

Swagger集成相对来说还是很简单的,虽然在集成过程中也出现了几个小问题,不过也很容易就解决了。今天文章的重点内容是Swagger分组功能,跟之前的参数校验文章一样,很多同学遇到这种分组场景时往往会选择创建多个实体类,虽然也能解决问题,只不过总是有点别扭。

不过遗憾的是,本文中Swagger的分组扩展只支持Swagger2,至于新版本Swagger3就不怎么支持了。如果有同学已经扩展好了,欢迎给我提pr呀。

以上就是java集成开发SpringBoot生成接口文档示例实现的详细内容,更多关于SpringBoot生成接口文档的资料请关注我们其它相关文章!

(0)

相关推荐

  • 教你利用springboot集成swagger并生成接口文档

    效果图 实现步骤 1.maven中引入jar包,不同版本的swagger可能页面效果不一样. <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.1</version> </dependency> <dependency> <groupId&g

  • java快速生成接口文档的三种解决方案

    目录 前言 方案一,使用japidocs 基本用法 方案2,swagger + knife4j 生成步骤 方案3,开源的接口文档生成工具 总结 前言 常常在项目收尾阶段,客户需要项目的接口文档,或者是一个大的sass平台,各个产品之间互相调用的时候,需要对方提供接口文档 通常来说,接口文档属于产品的技术沉淀,是一个长期积累的过程,然而,很多时候,开发阶段并不会想的那么多,结果到了需要接口文档的时候总是疲于应付,情急之下,往往采用最笨拙的办法,就是对照着项目代码,一个个拷贝吧 下面针对这个情况,小

  • Spring boot集成swagger2生成接口文档的全过程

    一.Swagger介绍 Swagger是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的web服务.目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器.这个解释简单点来讲就是说,swagger是一款可以根据restful风格生成的接口开发文档,并且支持做测试的一款中间软件. 二.使用swagger优势 1.对于后端开发人员来说 不用再手写Wiki接口拼大量参数,避免手写错误 对代码侵入性低,采用全注解的方式,开发简单 方法参数名修改.

  • SpringBoot结合Swagger2自动生成api文档的方法

    首先在pom.xml中添加如下依赖,其它web,lombok等依赖自行添加 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <dependency> <groupId>io.spri

  • SpringBoot集成Swagger2生成接口文档的方法示例

    我们提供Restful接口的时候,API文档是尤为的重要,它承载着对接口的定义,描述等.它还是和API消费方沟通的重要工具.在实际情况中由于接口和文档存放的位置不同,我们很难及时的去维护文档.个人在实际的工作中就遇到过很多接口更新了很久,但是文档却还是老版本的情况,其实在这个时候这份文档就已经失去了它存在的意义.而 Swagger 是目前我见过的最好的API文档生成工具,使用起来也很方便,还可以直接调试我们的API.我们今天就来看下 Swagger2 与 SpringBoot 的结合. 准备工作

  • java集成开发SpringBoot生成接口文档示例实现

    目录 为什么要用Swagger ? Swagger集成 第一步: 引入依赖包 第二步:修改配置文件 第三步,配置API接口 Unable to infer base url For input string: "" Swagger美化 第一步: 引入依赖包 第二步:启用knife4j增强 Swagger参数分组 分组使用说明 1.在bean对象的属性里配置如下注释 2.在接口参数的时候加入组规则校验 小结 大家好,我是飘渺. SpringBoot老鸟系列的文章已经写了两篇,每篇的阅读反

  • spring boot集成smart-doc自动生成接口文档详解

    目录 前言 功能特性 1 项目中创建 /src/main/resources/smart-doc.json配置文件 2 配置内容如下(指定文档的输出路径) 3 pom.xml下添加配置 4 运行插件 5 找到存放路径浏览器打开 6 测试结果 前言 smart-doc 是一款同时支持 java restful api 和 Apache Dubbo rpc 接口文档生成的工具,smart-doc 颠覆了传统类似 swagger 这种大量采用注解侵入来生成文档的实现方法. smart-doc 完全基于

  • SpringBoot整合Swagger3生成接口文档过程解析

    前后端分离的项目,接口文档的存在十分重要.与手动编写接口文档不同,swagger是一个自动生成接口文档的工具,在需求不断变更的环境下,手动编写文档的效率实在太低.与新版的swagger3相比swagger2配置更少,使用更加方便. 一.pom文件中引入Swagger3依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId

  • Go语言使用swagger生成接口文档的方法

    swagger介绍 Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言.Swagger与一组开源软件工具一起使用,以设计.构建.记录和使用RESTful Web服务.Swagger包括自动文档,代码生成和测试用例生成. 在前后端分离的项目开发过程中,如果后端同学能够提供一份清晰明了的接口文档,那么就能极大地提高大家的沟通效率和开发效率.可是编写接口文档历来都是令人头痛的,而且后续接口文档的维护也十分耗费精力. 最好是有一种方案能够既满足我们输出文档的需要又能

  • golang组件swagger生成接口文档实践示例

    目录 swagger介绍 gin-swagger实战 第一步:添加注释 第二步:生成接口文档数据 第三步:引入gin-swagger渲染文档数据 swagger介绍 Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言.Swagger与一组开源软件工具一起使用,以设计.构建.记录和使用RESTful Web服务.Swagger包括自动文档,代码生成和测试用例生成. 在前后端分离的项目开发过程中,如果后端同学能够提供一份清晰明了的接口文档,那么就能极大地提高大家

  • go swagger生成接口文档使用教程

    目录 前言 Swagger介绍 1.安装 2.检测是否安装成功 3.安装gin-swagger扩展 使用 1.添加注释 2.生成接口文档数据 3.引入gin-swagger渲染文档数据 总结 前言 这篇文章主要介绍了Go语言使用swagger生成接口文档的方法,希望能够对大家的学习或工作具有一定的帮助,需要的朋友可以参考下. 在前后端分离的项目开发过程中,如果后端同学能够提供一份清晰明了的接口文档,那么就能极大地提高大家的沟通效率和开发效率.那如何维护接口文档,历来都是令人头痛的,感觉很浪费精力

  • idea创建JAVA Class时自动生成头部文档注释的方法

    IDEA设置文档注释模板 创建Class文件时自动生成的头部注释如图 如何配置idea的头部注释格式,可以生成像之前的注释格式一样的文档注释? File->settings->Editor->File and Code Templates->Files->Class 原先模板 #if (${PACKAGE_NAME} && ${PACKAGE_NAME} != "")package ${PACKAGE_NAME};#end #parse(&

随机推荐