十一.SpringBoot配置Swagger3

十分钟空间

发布于 2022-08-17 14:23:36

1K0

发布于 2022-08-17 14:23:36

文章被收录于专栏：Springboot框架学习 Springboot框架学习Springboot框架学习

1.简介

▌swagger介绍

Swagger 是一套基于 OpenAPI 规范（OpenAPI Specification，OAS）构建的开源工具，后来成为了 Open API 标准的主要定义者，现在最新的版本为17年发布的 Swagger3（Open Api3）。国内绝大部分人还在用过时的swagger2（17年停止维护并更名为swagger3）对于 Rest API 来说很重要的一部分内容就是文档，Swagger 为我们提供了一套通过代码和注解自动生成文档的方法，这一点对于保证API 文档的及时性将有很大的帮助。 OAS本身是一个API规范，它用于描述一整套API接口，包括一个接口是哪种请求方式、哪些参数、哪些header等，都会被包括在这个文件中。它在设计的时候通常是YAML格式，这种格式书写起来比较方便，而在网络中传输时又会以json形式居多，因为json的通用性比较强。 SpringFox是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger2 集成到 Spring 中。

▌Swagger 主要包含了以下三个部分：

Swagger Editor：基于浏览器的编辑器，我们可以使用它编写我们 OpenAPI 规范。
Swagger UI：它会将我们编写的 OpenAPI 规范呈现为交互式的 API 文档，后文我将使用浏览器来查看并且操作我们的 Rest API。
Swagger Codegen：它可以通过为 OpenAPI（以前称为 Swagger）规范定义的任何 API 生成服务器存根和客户端 SDK 来简化构建过程。

▌SpringFox 3.0.0

SpringFox 3.0.0 发布了，SpringFox 的前身是 swagger-springmvc，是一个开源的 API doc 框架，可以将 Controller 的方法以文档的形式展现。
首先，非常感谢社区让我有动力参与这个项目。在这个版本中，在代码、注释、bug报告方面有一些非常惊人的贡献，看到人们在问题论坛上跳槽来解决问题，我感到很谦卑。它确实激励我克服“困难”，开始认真地工作。有什么更好的办法来摆脱科维德的忧郁！
注意：这是一个突破性的变更版本，我们已经尽可能地保持与springfox早期版本的向后兼容性。在2.9之前被弃用的api已经被积极地删除，并且标记了将在不久的将来消失的新api。所以请注意这些，并报告任何遗漏的内容。

▌此版本的亮点：

Spring5，Webflux支持（仅支持请求映射，尚不支持功能端点）。
Spring Integration支持。
SpringBoot支持springfox Boot starter依赖性（零配置、自动配置支持）。
具有自动完成功能的文档化配置属性。
更好的规范兼容性与2.0。
支持OpenApi 3.0.3。
零依赖。几乎只需要spring-plugin，swagger-core(https://github.com/swagger-api/swagger-core) ，现有的swagger2注释将继续工作并丰富openapi3.0规范

2.SpringBoot配置Swagger3

▌在pom.xml中引入Swagger3包。

<!--引入Swagger3-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

▌新建一个配置文件，编写配置文件

package com.tms.tblog.infrastructure.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30).apiInfo(
                new ApiInfoBuilder()
                        .title("Swagger2接口项目")
                        // 创建人信息
                        .version("1.0")
                        // 描述
                        .description("API接口")
                        .build()
        );

    }
}

▌如果使用的是SpringBoot2.6.1可能会有一个问题Failed to start bean 'documentationPluginsBootstrapper'; ，在启动文件里加上 @EnableWebMvc注解

package com.tms.tblog;

import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;

@SpringBootApplication
@MapperScan("com.tms.tblog.dao")
@EnableWebMvc
public class TBlogApplication {

    public static void main(String[] args) {
        SpringApplication.run(TBlogApplication.class, args);
    }

}

3.编写测试代码

▌在Controller中写上接口的api注解

/**
 * 账户控制
 */
@Api(tags = "账户接口")
@RequestMapping("/Account")
@RestController
@Log4j2
public class AccountController {

    @Resource
    private AccountService accountService;
    
    /**
     * 获取所有账户信息
     *
     * @return
     */
    @ApiOperation(value = "获取账户接口")
    @RequestMapping(value = "getAccount", method = RequestMethod.GET)
    public List<Account> getAccount() {
        List<Account> list = accountService.getAccount();
        return list;
    }
}

▌最后运行后展示结果是。启动程序，在浏览器中输入地址：http://localhost:8083/swagger-ui/index.html#/

4.常用的注解

swagger3	注解位置
@Api(tags=“接口描述”)	controller类上
@Operation(summary = “接口方法描述”)	controller 方法上
@ApiModelProperty(value = “字段描述”)	JavaBean的字段上
@ApiModel(“实体类的描述”)	JavaBean上
@EnableOpenApi	配置类上
@ApiImplicitParams	controller的方法参数中
@ApiImplicitParam	@ApiImplicitParams 下的的子参数
@Parameter(description = “参数描述”)	controller 方法的参数中