Springdoc OpenAPI 的使用

概念介绍

主要是用来统一管理api接口,而不是一个一个输入url去postman或者浏览器上进行测试

• Swagger 是一个广泛的 API 文档规范和工具集，核心是 OpenAPI 规范。
• Springfox Swagger 是 Swagger 的一个实现，专为 Spring 项目生成 Swagger 2 规范的 API 文档。
• Springdoc OpenAPI 是 Spring 的现代化库，专注于生成符合 OpenAPI 3.0 规范的 API 文档，逐渐取代了 Springfox。

为什么要使用 Springdoc OpenAPI?

Springfox 很久每更新了,不支持spring boot 3.x , 而Springdoc OpenAPI兼容spring 3.2.2版本的(自己测试过,3.4.x不行)

前置配置工作

1> pom.xml来引入相关依赖

注意Spring Boot 版本不能太高我此时的版本是3.2.2

springdoc依赖

        <!-- 加入 springdoc 依赖 -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.5.0</version>
        </dependency>

<repositories>
    <!--阿里云镜像-->
    <repository>
        <id>alimaven</id>
        <name>aliyun maven</name>
        <url>https://maven.aliyun.com/nexus/content/groups/public/</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

2> 配置yml

server:
  port: 8080 (你项目的端口号)

springdoc:
  api-docs:
    enabled: true # 开启OpenApi接口
    path: /v3/api-docs  # 自定义路径，默认为 "/v3/api-docs"
  swagger-ui:
    enabled: true # 开启swagger界面，依赖OpenApi，需要OpenApi同时开启
    path: /swagger-ui/index.html # 自定义路径，默认为"/swagger-ui/index.html"

3> 配置swagger

在config 包下编写SwaggerConfig

package org.xiaobai.forum.config;


import io.swagger.v3.oas.models.ExternalDocumentation;
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.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * @Author HHHY
 * @ClassName
 * @Date: 2024/4/2 14:21
 * @Description: Swagger 配置
 */

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("Spring Boot 中使用 Swagger UI 构建 RESTful API")
                        .contact(new Contact())
                        .description("百草中医药信息管理平台提供的 RESTful API")
                        .version("v1.0.0")
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("外部文档")
                        .url("https://springshop.wiki.github.org/docs"));
    }
}

4> 访问url

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

就有以下成功页面显示

如果觉得不行可以看看这个佬的博客:Spring Boot 3.x 引入springdoc-openapi (内置Swagger UI、webmvc-api)_springdoc-openapi-starter-webmvc-ui-优快云博客

​

4> 在这上面直接去测试我们的接口

​

各种注解的使用

1. @Tag

@Tag 主要是用来描述Controller类的基本信息

​

示例代码

import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@Tag(name = "Post", description = "帖子操作相关接口")
@RestController
public class PostController {

    @GetMapping("/posts")
    public List<Post> getAllPosts() {
        return postService.getAllPosts();
    }
}

2. @Schema

@Schema描述model类里面的类和字段信息

​

示例代码

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "帖子模型")
public class Post {

    @Schema(description = "帖子的唯一ID", example = "1")
    private Long id;

    @Schema(description = "帖子的标题", required = true)
    private String title;

    @Schema(description = "帖子的内容")
    private String content;
}

3. @Operation 

@Operation 描述一个API操作(方法信息)

​

示例代码:

import io.swagger.v3.oas.annotations.Operation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class PostController {

    @Operation(summary = "获取所有帖子", description = "返回系统中所有的帖子数据")
    @GetMapping("/posts")
    public List<Post> getAllPosts() {
        return postService.getAllPosts();
    }
}

4. @Parameter

@Parameter 描述一个方法里面的参数信息

​

示例代码:

import io.swagger.v3.oas.annotations.Parameter;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class PostController {

    @GetMapping("/posts")
    public List<Post> getPosts(
            @Parameter(description = "帖子类别") @RequestParam String category,
            @Parameter(description = "页码", example = "1") @RequestParam(defaultValue = "1") int page) {
        return postService.getPostsByCategory(category, page);
    }
}

小结

Springdoc OpenAPI 对应注解	描述
@Tag	描述类或方法的标签，帮助分组和分类API
@Schema	描述数据模型类的基本信息，标注类的描述、示例等
@Schema (字段级别)	描述字段的详细信息，如描述、示例、是否必填等
@Operation	描述API方法的功能，如摘要、详细描述、响应类型等
@Parameter	描述请求参数的信息，如名称、描述、默认值、示例等

 把 swagger里面的接口都导入到Postman

1> 启动项目,访问地址

Swagger UI

2> 确认连接有效并且把点进去的url复制

 3> 打开Postman进入工作空间

4> 在APIs中导⼊API，并完成测试

然后就可以看见生成了一堆的接口测试

其他注意事项

1> 我们的Spring Boot 版本不要太高, 此时我使用的是Spring Boot 3.2.2

2> 我们的Postman使用的是9.31.27(8.xx不能设置Link)