记忆角落

  • {{ item.name }}
  • SpringBoot 整合Swagger3 生成 API 接口文档
  • 引入依赖
  • 构建 Swagger 配置类
  • 编写实体类
  • 查看并测试接口
  • Swagger2 VS Swagger3
  • 首页
  • 关于
  • 归档
  • 邻居
  • 捐赠
  • 速查表

SpringBoot 整合Swagger3 生成 API 接口文档

  • 郭良俊只狗
  • 2022-01-11
  • 1

SpringBoot 整合Swagger3 生成 API 接口文档

相比于之前的 Swagger2，Swagger3 无疑新添了更多的特点，而相对集中地，主要集中在如下几点。

  • 支持 OpenApi 3.0.3
  • 兼容 Swagger2 的注释，而且进一步丰富了 open API 3.0 的规范
  • 支持 Webflux

既然 Swagger3 有了这么多的改变，那用法是不是还和 Swagger2 一样呢？答案是：不一样。

不过虽然两者的使用方式不一样，但是总体流程还是差不多了，只不过有些步骤有所小变动而已，只要你掌握了 Swagger2 的使用方法，那使用 Swagger3 起来就是需要注意小改动就行了。那接下来，我们就来看看，如何利用 Spring Boot 来集成 Swagger3，对我们的 Swagger2 进行一次升级！

引入依赖

创建项目后，在 pom.xml 文件中引入 Swagger3 的相关依赖。回忆一下，我们集成 Swagger2 时，引入的依赖如下：

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

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

而在 Swagger3 中，我们不需要再引入两个不同的依赖了，我们只需要引入一个依赖就足够，具体引入的依赖如下：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

而这部分，Swagger2 和 Swagger3 就有所不同了，Swagger2 需要添加两项不同依赖，而 Swagger3 只用添加一项依赖就可以了。

构建 Swagger 配置类

为了统一管理 Swagger，这里还是推荐给 Swagger3 添加一个配置类。当然这里也可以根据自己的需求，可要可不要，但总体来说还是建议配置。

平常在工作中，Swagger 的使用仅限于在开发环境，而在生产环境中，我们是要将其移除的。这里为了灵活管理，推荐大家在项目配置文件 application.yml 中添加关于 Swagger 开关的配置，比如这里我添加的配置如下，true 则代表开启 Swagger，false 则表示关闭 Swagger。

swagger:
  enabled: true

配置完成之后，我们就需要在 Swagger 配置类中获取 Swagger 开关的值了，关于具体用法就可以看下边配置代码。

package com.hcxt.sms.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @author: GuoLiangJun
 * @date: Created in 2021/12/13 21:59
 * Description: swagger 配置类
 * Created with IntelliJ IDEA.
 */
@Configuration
@EnableOpenApi
public class SwaggerConfig {

    @Value("${swagger.enabled}")
    Boolean swaggerEnabled;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo()).enable(swaggerEnabled)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.hcxt.sms.controller"))
                // 指定路径处理，PathSelectors.any()代表不过滤任何路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        // 作者信息
        Contact contact = new Contact("chinamobile", "https://chinamobile.com","service@chinamobile.com");
        return new ApiInfoBuilder()
                .title("短信发送API文档接口")
                .description("api接口文档")
                .version("1.0")
                .contact(contact)
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .build();
    }
}

这里的配置和 Swagger2 大同小异，这里最大的区别在于加入了从配置文件中获取 Swagger 开关的属性。这里也可以选择添加到 Swagger2 的配置类中，同样通过配置文件来控制是否开启 Swagger2。此外，还有就是 DocumentationType 属性的不同了，Swagger2 中我们使用的是 SWAGGER_2，而在 Swagger3 中，我们使用的则是 OAS_30。其实点进去 DocumentationType 的源码我们就可以发现，Swagger 已经是给我们定义好的，你用的是哪一个版本的 Swagger，那我们使用的属性值应该选择对应版本。三个版本的属性值对应如下：

image-20220111160042974

编写实体类

完成上面的步骤之后，我们的 Swagger 就配置好了，接下来我们就添加一个接口来看看 Swagger3 和 Swagger2 的不同。

1.新建实体类

package com.hcxt.sms.domain.vo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import javax.validation.constraints.Size;
import javax.validation.constraints.NotBlank;

/**
 * @author: GuoLiangJun
 * @date: Created in 2021/12/10 20:42
 * Description:
 * Created with IntelliJ IDEA.
 */

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(description = "发送信息参数类")
public class SendMessageInfo {

    @NotBlank(message = "手机号码不能为空!")
    @Size(min = 11,max = 11, message = "手机号码长度不正确")
    @ApiModelProperty(value = "手机号码")
    private String phoneNumber;

    @NotBlank(message = "ip地址不能为空!")
    @ApiModelProperty(value = "ipv4")
    private String ipv4Address;

}

2.新建接口

@RestController
@RequestMapping("/api")
@Slf4j
@Api(tags = "短信api")
public class SmsController {

    @Autowired
    SmsService smsService;

    @PostMapping("/sendLoginMessage")
    @ApiOperation(value = "发送登录验证码功能")
    @ApiResponses({
            @ApiResponse(code = 0,message = "请求成功",response=ResMsg.class),
            @ApiResponse(code = 1,message = "请求失败",response=ResMsg.class)
    })
    public ResMsg sendLoginMessage(@RequestBody @Valid SendMessageInfo sendMessageInfo){
        log.info(sendMessageInfo.toString());
        return smsService.sendLoginMessage(sendMessageInfo);
    }
}

查看并测试接口

启动我们的项目，然后在浏览器中访问如下地址，就可以访问项目的接口文档了。

http://localhost:28080/sms/swagger-ui/index.html

访问上面的地址后，如果出现下面的界面，则说明集成 Swagger3 就成功了。

这里也要注意一点，Swagger2 中的接口访问地址是：

http://localhost:28080/sms/swagger-ui.html

这里 Swagger2 和 Swagger3 是不同的，这里大家一定要注意，否则可能你继续拿着 Swagger2 接口访问地址来放到 Swagger3 项目中不适用。

image-20220111160517782

Swagger2 VS Swagger3

经过上面的步骤，我们就完成了 Spring Boot 集成 Swagger3 的实例测试了，而经过对比，也总结出了 Swagger2 和 Swagger3 的区别主要体现在如下几个方面：

  1. 所需依赖不同，Swagger2 需要添加两个依赖，而 Swagger3 则只需要添加一个依赖；
  2. 启用 Swagger 的注解不同，不知道大家有没有发现，无论是 Swagger2 还是 Swagger3 中的配置类，其实都是有一个注解用来启用 Swagger 的，不同之处在于 Swagger2 中用的是 @EnableSwagger2，而 Swagger3 中则用的是 @EnableOpenApi；
  3. 文档摘要信息（Docket）文件类型不同，可以发现在 Swagger 的配置类中，Swagger2 用的是 SWAGGER_2，而 Swagger3 中则用的是 OAS_3；
  4. Swagger UI 访问地址不同，在 Swagger2 中，如果我们要访问文档地址，需要访问 http://localhost:8080/swagger-ui.html，而在 Swagger3 中，则是访问 http://localhost:8080/swagger-ui/index.html；

参考:https://blog.csdn.net/github_39655029/article/details/122386870

© 2012 - 2024 记忆角落 网站统计    由又拍云CDN赞助 提供云储存服务
Theme by Wing 粤ICP备14056850号