SpringBoot 整合Swagger3 生成 API 接口文档 – 记忆角落

SpringBoot 整合Swagger3 生成 API 接口文档

/ 0评 / 0

SpringBoot 整合Swagger3 生成 API 接口文档

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

既然 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

发表评论

您的电子邮箱地址不会被公开。 必填项已用*标注