带有 Swagger 的 Spring Boot 示例 - Java

Swagger 是一种 API 规范和文档生成工具，其可以轻松地让您创建、发布、维护和文档化您的 APIs。

这个示例将展示如何使用 Spring Boot 和 Swagger 创建一个简单的 RESTful API，该 API 将返回 JSON 格式的一些名称和消息。该示例要求您已经熟悉了 Java、Spring Boot 和 Maven。

环境

• Java 8
• Spring Boot 2.5.2
• Maven

步骤

步骤一：创建一个 Maven 项目和 Spring Boot 应用程序

首先，在您的本地计算机上创建一个 Maven 项目和 Spring Boot 应用程序。您可以使用 Eclipse 或 IntelliJ IDEA 等集成开发环境来进行此操作，或者您可以在命令行下使用 Maven 从模板创建它。

步骤二：在 pom.xml 文件中添加依赖项

在 Maven 项目中使用 Spring Boot 和 Swagger，必须添加以下两个依赖项：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.10.5</version>
</dependency>

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.10.5</version>
</dependency>

步骤三：在 Spring Boot 应用程序的主类上启用 Swagger

在 Spring Boot 应用程序的主类上，使用 @EnableSwagger2 注释来启用 Swagger：

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class SpringBootSwaggerApplication {

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

}

步骤四：创建一个 RESTful 控制器

现在，您可以创建一个简单的 RESTful 控制器，该控制器将返回 JSON 格式的一些名称和消息。

@RestController 注释将该类标记为 Spring MVC 控制器，该控制器将处理传入的 HTTP 请求。

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

@RestController
public class GreetingController {

    @GetMapping("/greeting")
    public Map<String, String> greeting() {
        Map<String, String> greeting = new HashMap<>();
        greeting.put("name", "Swagger");
        greeting.put("message", "Hello, Swagger!");
        return greeting;
    }

}

步骤五：使用 Swagger 注释

Swagger 支持多种注释来描述 API，例如 Api、ApiOperation、ApiModel、ApiModelProperty 等。在此简单示例中，我们将使用 @Api 和 @ApiOperation 注释来描述我们的 API。

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

@RestController
@Api(value = "Greeting Controller", tags = { "Greeting" })
public class GreetingController {

    @GetMapping("/greeting")
    @ApiOperation(value = "Returns a greeting message", notes = "Returns a JSON with the greeting message")
    public Map<String, String> greeting() {
        Map<String, String> greeting = new HashMap<>();
        greeting.put("name", "Swagger");
        greeting.put("message", "Hello, Swagger!");
        return greeting;
    }

}

步骤六：在浏览器中访问 Swagger UI

现在，您可以在浏览器中访问 Swagger UI。它的默认 URL 是 http://localhost:8080/swagger-ui.html。

您应该能够转到 Swagger UI 界面，并查看您的新 API 的文档，包括您提供的摘要，说明和属性信息等。

步骤七：测试您的 API

现在，您可以使用 Swagger UI 来测试您的 API。在 Swagger UI 界面中，找到您的 API 端点并单击它。这将显示一个“尝试它”按钮，您可以单击它并提供您希望在请求中使用的参数。

总结

这个示例给出了在 Spring Boot 应用程序中使用 Swagger 的一些基本示例。通过使用 Swagger，您可以轻松地创建和文档化您的 API，并使其更容易被其他开发人员使用和消费。