springBoot对接swagger3

依赖

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

        <!-- 导入SpringBoot集成Open API 3.0（Swagger3.0）的坐标 -->
        <!-- 这个坐标它提供了一组注解和工具来集成Swagger UI和OpenAPI规范等-->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.7.0</version>
        </dependency>
    </dependencies>

配置文件

package com.cyz.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 io.swagger.v3.oas.models.info.License;
import org.springframework.boot.SpringBootConfiguration;
import org.springframework.context.annotation.Bean;
import java.util.HashMap;

/**
 * @author cyz
 * @since 2024/1/18 10:49
 */
@SpringBootConfiguration
public class SwaggerConfig {

    /***
     * 构建Swagger3.0文档说明
     * @return 返回 OpenAPI
     */
    @Bean
    public OpenAPI customOpenAPI() {

        // 联系人信息(contact)，构建API的联系人信息，用于描述API开发者的联系信息，包括名称、URL、邮箱等
        // name：文档的发布者名称 url：文档发布者的网站地址，一般为企业网站 email：文档发布者的电子邮箱
        Contact contact = new Contact()
                .name("kissStrong")                             // 作者名称
                .email("kissStrong@qq.com")                   // 作者邮箱
                .url("https://baidu.com/")  // 介绍作者的URL地址
                .extensions(new HashMap<String, Object>()); // 使用Map配置信息（如key为"name","email","url"）

        // 授权许可信息(license)，用于描述API的授权许可信息，包括名称、URL等；假设当前的授权信息为Apache 2.0的开源标准
        License license = new License()
                .name("Apache 2.0")                         // 授权名称
                .url("https://www.apache.org/licenses/LICENSE-2.0.html")    // 授权信息
                .identifier("Apache-2.0")                   // 标识授权许可
                .extensions(new HashMap<String, Object>());// 使用Map配置信息（如key为"name","url","identifier"）

        //创建Api帮助文档的描述信息、联系人信息(contact)、授权许可信息(license)
        Info info = new Info()
                .title("Swagger3.0 (Open API)")      // Api接口文档标题（必填）
                .description("学习Swagger框架而用来定义测试的文档")     // Api接口文档描述
                .version("1.2.1")                                  // Api接口版本
                .termsOfService("https://example.com/")            // Api接口的服务条款地址
                .license(license)                                  // 设置联系人信息
                .contact(contact);                                 // 授权许可信息
        // 返回信息
        return new OpenAPI()
                .openapi("3.0.1")  // Open API 3.0.1(默认)
                .info(info);       // 配置Swagger3.0描述信息
    }
}

测试类TestController

package com.cyz.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;

import javax.servlet.ServletOutputStream;
import javax.servlet.http.HttpServletResponse;
import java.io.FileInputStream;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

/**
 * @author cyz
 * @since 2024/1/18 10:55
 */
@RestController
@Tag(name = "TestController API",
        description = "测试接口")
public class TestController {

    @Operation(
            summary = "查询一个",
            description = "查询一个描述",
            parameters = {
                    @Parameter(name = "id", description = "学生ID", required = true, example = "1")
            }
    )
    @GetMapping("/get")
    public String get(@RequestParam("id") Integer id) {
        return "success =>> " + id;
    }

    @PostMapping(value = "/upload", consumes = "multipart/*", headers = "content-type=multipart/form-data")
    @Operation(summary = "上传", parameters = @Parameter(name = "file", description = "文件"))
    public String uploadFile(@RequestPart("file") MultipartFile file) {
        return file.getOriginalFilename();
    }

    @GetMapping(value = "/download")
    @Operation(summary = "下载", responses = @ApiResponse(content = @Content(mediaType = MediaType.APPLICATION_OCTET_STREAM_VALUE)))
    public void download(HttpServletResponse response) throws Exception {
        // 清空response
        response.reset();
        // 设置response的Header
        response.setCharacterEncoding("UTF-8");
        response.setContentType("application/octet-stream");
        String fileName = URLEncoder.encode("InvoiceTemplates.docx", String.valueOf(StandardCharsets.UTF_8));
        response.setHeader(HttpHeaders.CONTENT_DISPOSITION, "attachment;filename=" + fileName + ";" + "filename*=utf-8''" + fileName);
        ServletOutputStream outputStream = response.getOutputStream();
        FileInputStream inputStream = new FileInputStream("C:\\Users\\cyz\\Desktop\\InvoiceTemplates.docx");
        byte[] bytes = new byte[1024];
        int len = 0;
        while ((len = inputStream.read(bytes)) != -1) {
            outputStream.write(bytes, 0, len);
        }
        inputStream.close();
        outputStream.close();
    }


}

UI界面

访问http://ip:8080/swagger-ui.html