SpringBootWeb篇-入门了解Swagger的具体使用

 Swagger 使用步骤及解释：

Swagger 是一个强大的工具，用于规范和可视化 RESTful API 。

一、引入依赖

在您的 Spring Boot 项目的  pom.xml  文件中添加以下依赖：

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

这两个依赖分别用于生成 Swagger 文档的核心功能和提供用户界面。

二、配置 Swagger

创建一个配置类，例如  SwaggerConfig  ：

 

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.service.ApiInfo;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;



@Configuration

public class SwaggerConfig {



    @Bean

    public Docket api() {

        return new Docket(DocumentationType.SWAGGER_2)

              .apiInfo(apiInfo())

              .select()

              .apis(RequestHandlerSelectors.basePackage("您的控制器所在包路径"))

              .paths(PathSelectors.any())

              .build();

    }



    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()

              .title("您的项目名称 API 文档")

              .description("详细描述您的项目 API 的功能和用途")

              .version("1.0.0")

              .contact(new Contact("您的姓名", "您的网站链接", "您的邮箱"))

              .license("您的项目许可证信息")

              .licenseUrl("许可证的链接")

              .build();

    }

}

在上述配置中：

-  Docket  对象是 Swagger 的核心配置对象。

-  apiInfo  方法用于设置 API 的基本信息，如标题、描述、版本、联系人等。

-  select  方法用于选择要扫描的控制器和路径。

-  RequestHandlerSelectors.basePackage  指定要扫描的包路径，以包含其中的控制器。

-  PathSelectors.any  表示匹配所有路径。

三、编写控制器

在您的控制器类中，使用注解来详细描述接口：

import io.swagger.annotations.Api;

import io.swagger.annotations.ApiOperation;

import io.swagger.annotations.ApiParam;

import io.swagger.annotations.ApiResponse;

import io.swagger.annotations.ApiResponses;



@RestController

@Api(tags = "用户管理")

public class UserController {



    @GetMapping("/users")

    @ApiOperation("获取用户列表")

    @ApiResponses({

            @ApiResponse(code = 200, message = "成功获取用户列表"),

            @ApiResponse(code = 400, message = "请求参数错误"),

            @ApiResponse(code = 500, message = "服务器内部错误")

    })

    public List<User> getUserList() {

        // 实现逻辑

    }



    @PostMapping("/users")

    @ApiOperation("创建新用户")

    public User createUser(

            @ApiParam(name = "user", value = "用户对象", required = true) @RequestBody User user) {

        // 实现逻辑

    }

}

在上述控制器的注解中：

-  @Api  注解用于对控制器进行分类和标记。

-  @ApiOperation  注解用于描述每个接口的功能。

-  @ApiParam  注解用于描述接口的参数。

-  @ApiResponse  和  @ApiResponses  注解用于描述接口可能返回的响应码和响应消息。

四、启动应用并访问 Swagger UI

启动您的 Spring Boot 应用，然后在浏览器中访问  http://localhost:8080/swagger-ui.html  ，您将看到生成的详细接口文档。

文档中会展示每个接口的请求方法、路径、参数、响应等信息，并且提供了测试接口的功能，您可以直接在页面上输入参数并发送请求进行测试。