java：springboot3集成swagger（springdoc-openapi-starter-webmvc-ui）

news2024/12/25 13:54:44

背景

网上集成 swagger 很多都是 Springfox 那个版本的，但是那个版本已经不更新了，springboot3 集成会报错 Typejavax.servlet.http.HttpServletRequest not present，我尝试了很多才知道现在用 Springdoc 了，今天我们来入门一下

名词解释

提起 api 文档，一般都能想起 swagger，但是除了 swagger，你可能还听说过OpenAPI、Springfox、Springdoc，这些和 swagger 又有什么关系呢？

OpenAPI

官网
是一个组织（OpenAPI Initiative），他们指定了一个如何描述HTTP API的规范（OpenAPI Specification）。既然是规范，那么谁想实现都可以，只要符合规范即可。

Swagger

官网
它是SmartBear这个公司的一个开源项目，里面提供了一系列工具，包括著名的 swagger-ui。swagger是早于OpenApi的，某一天swagger将自己的API设计贡献给了OpenApi，然后由其标准化了。

Springfox

官网
是Spring生态的一个开源库，是Swagger与OpenApi规范的具体实现。我们使用它就可以在spring中生成API文档。以前基本上是行业标准，目前最新版本可以支持 Swagger2, Swagger3 以及 OpenAPI3 三种格式。但是其从 2020年7月14号就不再更新了，不支持springboot3，所以业界都在不断的转向我们今天要谈论的另一个库Springdoc，新项目就不要用了。

Springdoc

官网
算是后起之秀，带着继任Springfox的使命而来。其支持OpenApi规范，支持Springboot3，我们的新项目都应该使用这个。

总结

Swagger 和 OpenAPI 是一对相关的概念，Swagger 是前身，OpenAPI 是其演进和规范化。

Springfox和 Springdoc 是一对相关的概念，
Springfox是一个将 Swagger 2.x 规范集成到 Spring Boot 项目中的库，提供了用于定义 API 和生成 Swagger UI 的功能。
Springdoc 是一个将 OpenAPI 3.x 规范集成到 Spring Boot 项目中的库，提供了用于定义 API 和生成 Swagger UI 的功能，使用原生的 Spring 5 注解。

如果你使用的是 Swagger 2.x，可以选择 Springfox；
如果你使用的是 OpenAPI 3.x，可以选择 Springdoc。

Springdoc简单示例

1、引入依赖

<dependency>
   <groupId>org.springdoc</groupId>
   <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
   <version>2.2.0</version>
</dependency>

2、设置好端口号，也就是你项目的端口号
application.properties

server.port=9090

3、浏览器访问 http://localhost:9090/swagger-ui/index.html
或者访问
http://localhost:9090/swagger-ui.html 也会重定向到 http://localhost:9090/swagger-ui/index.html

这里默认配置是这个，所以才可以重定向
springdoc.swagger-ui.path=/swagger-ui.html

在这里插入图片描述
是不是超简单，接下来看看还有什么其他的配置

其他配置示例

接下来我简单写一个配置，大家看看映射到界面是哪里。
1、创建配置类
config/SpringDocConfig.java

package com.zhangyu.config;

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("Lvan的Swagger")
                .description("这是一个springboot测试")
                .version("v1.0.0")
                .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                .description("Lvan的博客")
                .url("https://blog.csdn.net/weixin_43972437"));
    }
}

2、在控制器上加一些注解
主要是下面的 @Tag、@Operation 注解

package com.zhangyu.controller;

import com.zhangyu.mapper.UserMapper;
import com.zhangyu.model.UserForJpa;
import com.zhangyu.model.UserForMybatis;
import com.zhangyu.repository.UserRepository;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@RestController
@RequestMapping("/users")
@Tag(name = "用户模块", description = "用户模块的描述")
public class UserController {

    @Autowired
    private UserRepository userRepository;

    @Autowired
    private UserMapper userMapper;

    @GetMapping("getAllForJpa")
    @Operation(summary = "获取用户信息-jpa方式", description = "以jpa的方式获取用户")
    public List<UserForJpa> getAllUsersForJpa() {
        return userRepository.findAll();
    }

    @GetMapping("getAllForMybatis")
    @Operation(summary = "获取用户信息-Mybatis方式", description = "以Mybatis的方式获取用户")
    public List<UserForMybatis> getAllUsersForMybatis() {
        return userMapper.findAll();
    }
}