Swagger的使用

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。

在软件开发过程中，Swagger被广泛用于API的设计、文档编写、测试和API服务的管理。它帮助开发者更快地开发API，同时也让API的使用者更容易理解和使用这些API。

 下面将通过对Swagger3的使用进行讲解

1、引入依赖

   <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version> <!-- 请检查最新版本 -->
        </dependency>

2、配置Swagger的配置类

这里使用的是.apis(RequestHandlerSelectors.any())，是扫描当前项目中的所有的接口

Swagger3在配置类中使用@EnableOpenApi注解

package com.example.test2.Test.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;


@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket apiDocket() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

这样会统计所有的接口信息 

如果我们至少想要统计某个模块下的接口信息的话，我们使用

.apis(RequestHandlerSelectors.basePackage("你的控制器所在的包路径"))，用于只统计当前包路径下的接口的信息

package com.example.test2.Test.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;


@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket apiDocket() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.test2.Test.Controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

 下面是com.example.test2.Test.Controller包路径下的接口的信息，两个Controller层的类

package com.example.test2.Test.Controller;

import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Api(tags = "测试Swagger3")
public class Test001 {
    @GetMapping("/test001")
    public String test001(){
        String a = "这个是一个测试Swagger2的接口";
        return a;
    }

    @PostMapping("/test002")
    public String test002(){
        String a = "这个是一个测试Swagger2的接口";
        return a;
    }
}

package com.example.test2.Test.Controller;

import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Api(tags = "测试Swagger4")
public class Test002 {
    @GetMapping("/test003")
    public String test003()
    {
        String a = "test003";
        return a;
    }
}

3、生成Swagger文档

在Controller层中使用@Api注解定义和描述API信息

tags：这是 @Api 注解的一个属性，用于定义一个或多个标签，这些标签可以将 API 分组并在 Swagger UI 中显示。每个标签对应一组操作。即使是在不同的类中只要是相同分组的就会在同一组里显示。

4、访问Swagger3的文档

地址：http://localhost:你的端口号/swagger-ui/index.html