SpringDoc --＞ Swagger的完美替代品 使用详解【可完全匹配新版Springboot】可视化RESTful风格 Web 服务接口api文档

        使用了最新 SpringBoot 版本的朋友们在使用 swagger 时一定都碰到了很多烦恼，各种报错。废话不多说，既然你已经看到了这里就说明你已经查阅了很多资料，对swagger有了一定的了解。话不多说，直接上菜。

| 造成问题的原因

        当然咯，上菜之前咱还是得讲解一下，为何频频出错；原因很简单，随着时间的推移，springboot 一直在更新迭代，而 swagger 已经1年多没有再进行升级（当前时间：北京时间3月6日17：38分），因此版本已经不再兼容；

上菜

• 我当前所使用的 springboot 及 springcloud 对应的版本

父项目做了版本管理

 

| 需要在项目中添加的springdoc依赖

<!--  https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui  -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.6.6</version>
        </dependency>

| yml文件配置

#springdoc接口文档指定接口包扫描
springdoc:
 packages-to-scan: com.xxxxxxxx
#或者指定访问接口路径扫描
#  paths-to-match: /api/user/**

• 只需扫描sb启动类下的包即可 

| 配置类

• 项目中添加配置类，配置类的详解查看注释即可

package com.yangdaxian.payment.config;

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

/**
 * http://127.0.0.1:9090/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/
 *
 * @ClassName SpringDocConfig
 * @Description TODO /v3/api-docs
 * @Author yangdaxian
 * @DATE 2022/2/23 09:46:16
 * @Version 1.0
 */
@Configuration
public class SpringDocConfig {

    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(info())
/*添加对JWT对token的支持(本步骤可选) 在添加OpenApiConfig类上添加Components信息：然后在OpenApi中注册Components:*/
                .components(components())
                .externalDocs(externalDocumentation());
    }

    private License license() {
        return new License()
                .name("MIT")
                .url("https://opensource.org/licenses/MIT");
    }

    private Info info() {
        return new Info()
                .title("Benjamin Yang's Open API")
                .description("Benjamin Yang")
                .version("v0.0.1")
                .license(license());
    }

    private ExternalDocumentation externalDocumentation() {
        return new ExternalDocumentation()
                .description("Benjamin Yang's Blog")
                .url("https://blog.csdn.net/m0_55710969?spm=1001.2014.3001.5343");
    }

    /* 添加对JWT对token的支持(本步骤可选)
     在添加OpenApiConfig类上添加Components信息：*/
    private Components components() {
        return new Components()
                .addSecuritySchemes("bearer-key", new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT"));
    }
    /*然后在OpenApi中注册Components:*/
/*    @Bean
    public OpenAPI springShopOpenAPI2() {
        return new OpenAPI()
                .info(info())
                .components(components())
                .externalDocs(externalDocumentation());
    }
    */
//    /*在需要使用Authorization的接口上添加：*/
//    @Operation(security = { @SecurityRequirement(name = "bearer-key") })

}

使用姿势

        很简单，只需要几个注解即可轻松搞定；

| 实体类api文档注解

这里可以看到，使用的还是swagger3包中的内容。

ps：这是码友们对它的社区版升级啦，并非官方，但非常好用哦

实体类的相关注解 ：如图所示

• 更多使用方式就需要点进注解自己参考啦

| Controller控制层 / 接口方法层

        同样，还是导入的swagger3的包，这里仅做几个重要注解参数的使用，更多姿势还请诸位亲自进入接口类解锁；如图所示：

接下来启动项目，访问

127.0.0.1:9090/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/

• 即可看到如下图所示的操作文档说明啦~

• 查看方法，也可以像postman一样测试哦

• 实体类效果如图

关于新版 springboot 整合 springdoc 到这里便宣告结束啦，祝 玩的愉快！ 

---

Thanks