一.Swagger3的主要功能

• 自动生成API文档：Swagger3可以根据项目中的注解自动生成API文档，大大提高了开发效率。
• 可视化界面：Swagger3提供了可视化界面，方便开发者查看和测试API。
• 支持多种格式：Swagger3不仅支持JSON格式，还支持YAML格式，可以减少文本长度，提高可读性。
• 组件化：Swagger3采用了组件化的方式来定义API元素，使得API定义更加模块化和可扩展。
• 安全认证：Swagger3支持API的安全认证，可以通过配置安全方案和上下文来保护API的安全。

二.Swagger3的集成与使用

1. 引入依赖：在项目中引入Swagger3的依赖，通常是通过Maven或Gradle等构建工具来完成的。
2. 配置Swagger：创建Swagger配置类，通过注解和配置来定制Swagger的文档信息、安全认证等。
3. 编写注解：在Controller类和方法上编写Swagger的注解，如@Api、@ApiOperation、@ApiModel、@ApiModelProperty等，这些注解会被Swagger解析并生成对应的API文档。
4. 启动项目：启动项目后，通过访问Swagger的UI界面（通常是http://localhost:端口号/swagger-ui/index.html）来查看和测试API。

三、Swagger3的常用注解

1. @Api：用于接口类上，用以对当前的接口类做整体声明。
2. @ApiOperation：用于接口方法上，用以描述具体的方法。
3. @ApiModel：用于实体类上，描述实体类的整体信息。
4. @ApiModelProperty：用于实体类的属性上，描述属性的详细信息。
5. @ApiImplicitParams和@ApiImplicitParam：用于描述接口方法的隐式参数。
6. @ApiResponses和@ApiResponse：用于描述接口方法的响应信息。
7. @ApiIgnore：用于忽略某个接口或方法，使其在Swagger文档中不可见。

四、Swagger3与Swagger2的区别

1. OpenAPI规范的支持：Swagger3采用OpenAPI规范来定义API，这使得API定义更加规范化和标准化。而Swagger2是OpenAPI规范的前身。

2. 支持的格式：Swagger3除了支持JSON格式外，还支持YAML格式。而Swagger2主要支持JSON格式。

3. 特性支持：Swagger3支持异步API、Webhook等特性，而Swagger2则没有这些支持。

4. 组件化：Swagger3采用了组件化的方式来定义API元素，更加模块化和可扩展。而Swagger2的组件化支持相对较弱。

五、Swagger3的优缺点

优点：

1. 自动生成API文档，提高开发效率。
2. 提供可视化界面，方便查看和测试API。
3. 支持多种格式和组件化定义，提高API的可读性和可扩展性。

缺点：

1. 在某些Spring Boot版本中可能存在兼容性问题，需要额外配置或降级版本。
2. 对于复杂的API定义和文档定制，可能需要较多的配置和注解编写。
3. 综上所述，Swagger3是一个功能强大且灵活的API文档生成和可视化工具，它可以帮助开发者更好地设计和维护API文档，提高开发效率和文档的可读性。在实际项目中，开发者应根据项目需求和团队习惯来选择合适的版本和配置方式。

六.SpringBoot配置Swagger3

1.在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>

2.新建一个配置文件，编写配置文件

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()
        );

    }
}

3.兼容问题处理

如果使用的是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);
    }

}

七编写测试代码

1.在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;
    }
}

2.运行结果

八.常用的注解

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

推荐文章

评论