SpringBoot 3.2.5 引入Swagger(OpenApi)

springdoc-openapi 和 swagger 都可以用，用其中一个就行，不用两个都引入。

这里简单记录以下springdoc-openapi。

springdoc-openapi(Java库)有助于使用 SpringBoot 项目 自动生成 API 文档。

pom文件

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0modelVersion>
    <parent>
        <groupId>org.springframework.bootgroupId>
        <artifactId>spring-boot-starter-parentartifactId>
        <version>3.2.5version>
        <relativePath/>
    parent>
    
 	
    <groupId>openApigroupId>
    <artifactId>openApiartifactId>
    <version>3.2.5version>

    <name>openApiname>
    <description>这里写你自己的项目描述description>

    <properties>
        <project.build.sourceEncoding>UTF-8project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8project.reporting.outputEncoding>
        <java.version>17java.version>
    properties>

    <dependencies>
        
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-webartifactId>
            <version>3.2.5version>
        dependency>

        
        <dependency>
            <groupId>org.projectlombokgroupId>
            <artifactId>lombokartifactId>
            <version>1.18.30version>
        dependency>

        
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-validationartifactId>
            <version>3.2.5version>
        dependency>
        <dependency>
            <groupId>jakarta.validationgroupId>
            <artifactId>jakarta.validation-apiartifactId>
            <version>3.0.2version>
        dependency>

        
        <dependency>
            <groupId>org.springdocgroupId>
            <artifactId>springdoc-openapi-starter-webmvc-uiartifactId>
            <version>2.5.0version>
        dependency>
    dependencies>
project>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

配置文件

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

//也有其他的扩展，有兴趣的可自行翻阅官网
@Configuration
public class SpringDocConfig {
	//个人认为，以下括号里的内容，都可乱写，写啥都行，只要是字符串就行
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("OpenApi的Swagger")
                        .description("springdoc-openapi-starter-webmvc-ui")
                        .version("springdoc-openapi v2.5.0")
                        .license(new License()
                                .name("SprigBoot3.2.5")
                                //url，这里写的是SpringBoot的地址
                                .url("https://spring.io/projects/spring-boot"))
                ).externalDocs(new ExternalDocumentation()
                        .description("springdoc-openapi v2.5.0")
                        //url,写的是springdoc-openapi的地址
                        .url("https://springdoc.org/#google_vignette"));
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

启动类

import lombok.extern.slf4j.Slf4j;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@Slf4j
@SpringBootApplication
public class BigEventApplication implements CommandLineRunner {
    public static void main(String[] args) {
        SpringApplication.run(BigEventApplication.class, args);
    }

    @Override
    public void run(String... args) {
    	//端口号默认8080
        log.info("Tomcat在端口 " + 8080 + " (http)上启动：\n");
        
        String hostname = "localhost";
        String http = "http://";
        
        log.info("Api文档 浏览器访问地址如下：");
        log.info(http + hostname + ":" + 8080 + "/swagger-ui/index.html\n");
        
        log.info("ApiFox的 URL方式 导入路径为：");
        log.info(http + hostname + ":" + 8080 + "/v3/api-docs\n");
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

Controller 层

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import lombok.RequiredArgsConstructor;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@Validated
@RestController
@RequiredArgsConstructor
@Tag(name = "Xxx名字", description = "这里可以多写几个字，用来描述xxx，描述的详细一点")
@RequestMapping("/路径")
public class XxxController {

    private final XxxService service;
    
    @Operation(summary = "删除", description = "根据 id 删除")
    @DeleteMapping("/delete/{id}")
    public Result<String> clean(@NotBlank(message = "id 不可为空") @PathVariable String id) {
        boolean b = service.removeById(id);
        return b ? Result.success("删除成功") : Result.error("删除失败");
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

启动成功后，可以直接从控制台点击这俩访问地址
http://localhost:8080/swagger-ui/index.html
http://localhost:8080/v3/api-docs

ApiFox

我用的接口测试工具是Apifox
把导入地址复制进去，就可以测试接口了

题外话

• 你没钱，别人对你的态度，基本都是真诚的：说教、训斥、排挤……都是真的，因为他们找到了存在感。
• 你有钱，别人对你的态度 就不一定是真的了，所谓的夸赞，可能是虚情假意，因为 你比他们强，他们嫉妒你。