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

本文介绍: springboot3集成 swagger 报错Ty pe javax.servlet.http.Ht t pSe r v letReques t not present，来使用 springdoc–open api–starter–web mvc–ui

背景

网上集成 swagger 很多都是 Spr in gfo x 那个版本的，但是那个版本已经不更新了，springboot3 集成会报错 Ty pe javax.servlet.http.HttpSe r v letRequest not present，我尝试了很多才知道现在用 Sp r in gd oc 了，今天我们来入门一下

名词解释

提起 api 文档，一般都能想起 swagger，但是除了 swagger，你可能还听说过OpenAPI、Spr in gfo x、Spr ingd o c，这些和 swagger 又有什么关系呢？

OpenAPI

官网
是一个组织（OpenAPI Ini ti a tive），他们指定了一个如何描述HTTP API的规范（OpenAPI Spec i fi cat ion）。既然是规范，那么谁想实现都可以，只要符合规范即可。

Swagger

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

Spr ingfo x

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

Springd o c

官网
算是后起之秀，带着继任Springfo x的使命而来。其支持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/SpringDocCon fig.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();
    }
}