springboot配置springdoc的使用日记之添加springdoc

本次主要是配置关于springdoc-openapi-starter-webmvc-ui中的过程和遇到的一些问题；

首先在搭建好的springboot中添加maven依赖：

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

依赖版本可以自行调整；第一个依赖是必要项；

添加后启动就可以直接访问了，默认的访问地址(端口号修改为自己的项目端口号)：http://localhost:8080/swagger-ui/index.html

正常情况下就可以看到一个这样的访问页面了；

如果访问出现404可以先排查以下几项：

1、是否配置了访问拦截；

2、项目是否有准确启动；

3、去添加相应的配置项；

如果出现可以正常打开页面，但是展示的是swagger的官网页面，非自己的系统接口，可能是因为框架配置了统一封装返回导致了http://localhost:8080/v3/api-docs无法正常访问返回；

错误样例：

解决方案可移步springdoc的使用日记之解决统一返回封装的壁垒查看是否能提供解决思路~

如果想要自定义一些访问地址或者其他参数可以在配置文件或yml中添加以下设置：

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

然后如果还想要自定义访问页面的标题可以添加一个springdoc的配置类

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


@Configuration
public class SpringDocConfig {
    /**
     * 一个自定义的 OpenAPI 对象
     *
     * @return 一个自定义的 OpenAPI 对象
     */
    @Bean
    public OpenAPI customOpenApi() {
        return new OpenAPI()
                //.components(new Components()
                        // 设置 spring security jwt accessToken 认证的请求头 Authorization: Bearer xxx.xxx.xxx
                        //.addSecuritySchemes("openApiSecurityScheme", new SecurityScheme()
                        //        .type(SecurityScheme.Type.HTTP)
                        //        .bearerFormat("JWT")
                        //        .in(SecurityScheme.In.HEADER)
                        //        .name("Authorization")
                        //        .scheme("Bearer")))
                // 设置标题、版本等信息
                .info(new Info()
                        //设置标题
                        .title("Springdoc文档展示系统")
                        // 配置版本号
                        .version("0.0.1-SNAPSHOT")
                        // 配置文档描述
                        .description("SpringBoot3集成Swagger3示例文档")
                        // 配置作者信息
                        .contact(new Contact().name("菜鸟日记~").url("https://blog.csdn.net/qq_53900384?spm=1011.2415.3001.5343").email("xxx@xx.com"))
                        // 概述信息
                        .summary("Springdoc文档展示系统")
                        .termsOfService("")
                        // 配置License许可证信息
                        .license(new License()
                                .name("Apache 2.0")
                                .url("https://www.apache.org/licenses/LICENSE-2.0.html")));
    }
}

配置后访问样例：