正文

从零开始：轻松上手Swagger3与Spring Boot集成，快速构建API文档

/0 浏览量
0710

在软件开发领域，API文档是开发者之间沟通的桥梁，它能够让使用者快速了解和使用你的API。Swagger是一个流行的API文档和交互式界面工具，可以让你轻松生成和测试API文档。本文将带你从零开始，使用Swagger3与Spring Boot集成，快速构建API文档。

一、准备工作

在开始之前，请确保你的开发环境中已经安装了以下工具：

  • Java Development Kit (JDK)
  • Maven 或 Gradle
  • Spring Boot

二、创建Spring Boot项目

  1. 使用Spring Initializr：访问Spring Initializr（https://start.spring.io/），选择Java、Spring Boot版本，然后选择所需的依赖项，例如Spring Web、Spring Boot DevTools等。生成项目结构后，下载项目压缩包。

  2. 解压项目：将下载的项目压缩包解压到本地。

  3. 导入项目：使用IDE（如IntelliJ IDEA或Eclipse）导入项目。

三、添加Swagger3依赖

在pom.xml文件中，添加以下依赖项：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

或者，如果你使用Gradle，则添加以下依赖项：

implementation 'io.springfox:springfox-boot-starter:3.0.0'

四、配置Swagger3

  1. 创建Swagger配置类：在项目中创建一个配置类，用于配置Swagger3。
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();
    }
}
  1. 启动类添加@EnableOpenApi：在启动类上添加@EnableOpenApi注解，启用Swagger3。
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
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;

@SpringBootApplication
@EnableOpenApi
public class SwaggerApplication {

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

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

五、编写API接口

创建一个简单的API接口，用于测试Swagger3。

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class SwaggerController {

    @GetMapping("/hello")
    public String hello() {
        return "Hello, Swagger!";
    }
}

六、启动项目

启动Spring Boot项目，访问http://localhost:8080/swagger-ui/，你将看到Swagger3的UI界面。

七、总结

通过以上步骤，你已经成功将Swagger3与Spring Boot集成，并快速构建了API文档。Swagger3可以让你轻松地测试和文档化API，提高开发效率。希望本文能帮助你入门Swagger3，祝你开发愉快！

-- 展开阅读全文 --