山东大学软件学院创新实训知航KnowVoyage后端——Swagger后端API暴露

一、需求要求

  后端的项目创建已经实现了各个数据库的基本功能了，但是我们的项目后端和前端是分开实现的，并且前后端的开发是同步进行的，所以后端如何将自己的接口API暴露给前端是十分重要的，而项目是动态变化的，始终更改api文档也是不现实的，所以我们采用Swagger工具进行后端API的提供。

二、Swagger是什么

  Swagger 是一个用于生成、描述和调用 RESTful 接口的 Web 服务。通俗的来讲，Swagger 就是将项目中所有（想要暴露的）接口展现在页面上，并且可以进行接口调用和测试的服务，而且Swagger 遵循了 OpenAPI 规范来规范 RESTful 服务开发过程。
  总是Swagger会让我们的接口可视化的展示出来，从而方便的将api暴露给前端。

三、Swagger使用

1.依赖配置

  在我们的SpringBoot3项目中，原先的Swagger2已经停止维护，所以我们使用springdoc-openapi来实现Swagger。它可以自动扫描 @RestController 生成 API 文档，并支持 OpenAPI 3.0 标准，提供交互式 Swagger UI 界面，而且还与 Spring Security 兼容。
  依赖如下：

<!--Swagger文档生成-->
<dependency>
	<groupId>org.springdoc</groupId>
	<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
	<version>2.5.0</version>
</dependency>

2.访问文档

运行项目后，可在如下网址查看自己的swagger生成。

Swagger UI 界面：

http://localhost:8080/swagger-ui.html

OpenAPI JSON：

http://localhost:8080/v3/api-docs

3.基本使用

<一> 控制器层注解

1. @Tag
   描述整个控制器类

   @Tag(name = "用户API", description = "用户相关操作")
   @RestController
   public class UserController { ... }

3. @Operation
   描述单个接口方法

   @Operation(summary = "创建用户", description = "需提供用户名和密码")
   @PostMapping("/users")
   public void createUser() { ... }

4. @Parameter
   描述方法参数（路径/查询参数）

   @GetMapping("/users/{id}")
   public User getUser(
       @Parameter(description = "用户ID", example = "1") @PathVariable Long id
   ) { ... }

<二> 模型层注解

@Schema
描述实体类或字段

   @Schema(description = "用户实体")
   public class User {
       @Schema(description = "用户ID", example = "123")
       private Long id;
   }

<三> 特殊场景注解

1. @ApiResponse
   描述接口响应状态码

   @ApiResponse(responseCode = "404", description = "用户不存在")
   @GetMapping("/users/{id}")
   public User getUser() { ... }

2. @Hidden
   隐藏接口或字段（不生成文档）

   @Hidden  // 隐藏此接口
   @GetMapping("/secret")
   public String secret() { ... }

3. @RequestBody + @Schema
   描述请求体

   @PostMapping("/users")
   public void createUser(
       @RequestBody @Schema(description = "用户数据") User user
   ) { ... }

四、Swagger其他配置

  我们在SwaggerConfig类中可以对Swagger进行配置，为其添加名称等。

package com.knowvoyage.knowvoyageserver.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("KnowVoyage后端API文档")
                        .version("1.0")
                        .description("KnowVoyage是我们团队合作构建的一个借助山大t提供的deepseek接口对考研408进行刷题、做题、问答的一个应用，该应用后端采用SpringBoot3+Mybatis+MySQL架构，目的在于设计并实现用户的后端处理。")
                        .contact(new Contact()
                                .name("ffqwq & zzz")));
    }
}

展示：