MONI后台管理系统-swagger3(springdoc-openapi)集成

springdoc-openapi Java 库有助于使用 Spring Boot 项目自动生成 API 文档。springdoc-openapi 通过在运行时检查应用程序来根据 Spring 配置、类结构和各种注释推断 API 语义。
该库会自动生成 JSON/YAML 和 HTML 格式的页面文档。生成的文档可以使用swagger-api注释进行补充。
github地址 官网

1. 项目依赖版本

• Spring-Boot: 3.1.0

2. 引入依赖

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

3. 配置

package com.omni.admin.swagger;

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import jakarta.annotation.Resource;
import org.springframework.boot.autoconfigure.condition.ConditionalOnExpression;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * SpringDoc配置
 **/
@Configuration
@ConditionalOnExpression("${springdoc.api-docs.enabled:true}")
public class SwaggerDocConfig {

    @Resource
    private SwaggerDocProperties springDocProperties;

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI().info(new Info().title(springDocProperties.getTitle()).version(springDocProperties.getApplicationVersion()))
                .addSecurityItem(new SecurityRequirement().addList(springDocProperties.getTokenName()))
                .components(new Components().addSecuritySchemes(springDocProperties.getTokenName(),getSecurityScheme()));
    }

    private SecurityScheme getSecurityScheme(){
        return new SecurityScheme().name(springDocProperties.getTokenName()).in(SecurityScheme.In.HEADER).type(SecurityScheme.Type.APIKEY).scheme("basic");
    }
}

package com.omni.admin.swagger;

import lombok.Data;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.autoconfigure.condition.ConditionalOnExpression;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;

import java.util.List;

/**
 * swagger配置类
 **/
@Data
@Configuration
@ConfigurationProperties(prefix = "springdoc")
@ConditionalOnExpression("${springdoc.api-docs.enabled:true}")
public class SwaggerDocProperties {

    /**
     * 项目应用名
     */
    @Value("${spring.application.name:接口文档}")
    private String applicationName;

    /**
     * 项目名称
     */
    private String title = "Omni-Admin后台管理系统接口文档";

    /**
     * 项目版本信息
     */
    private String applicationVersion = "1.0.0";

    /**
     * 项目描述信息
     */
    private String applicationDescription;

    /**
     * 认证token的名称
     */
    private String tokenName = "X-Access-Token";


    /**
     * 文档组配置
     */
    private List<Group> groups;


    @Data
    public static class Group{
        private String modelName;

        /**
         * 组名称
         */
        private String name;

        /**
         * 组所属的包
         */
        private String packageName;
    }
}

4. properties配置

这里需要做一些说明：其中配置了排序相关和分模块。还有默认访问是全部文档是展开的，可以配置默认合并。

# springdoc接口文档配置 配置参考 springdoc.md
springdoc.api-docs.enabled=true
springdoc.swagger-ui.tags-sorter=alpha
springdoc.swagger-ui.operations-sorter=method
springdoc.group-configs[0].group=A-平台管理
springdoc.group-configs[0].packages-to-scan[0]=auth.platform.service.platform
springdoc.group-configs[1].group=B-标签管理
springdoc.group-configs[1].packages-to-scan[0]=auth.platform.service.tag
springdoc.group-configs[2].group=C-配置中心
springdoc.group-configs[2].packages-to-scan[0]=auth.platform.service.configcenter
springdoc.group-configs[3].group=D-日志管理
springdoc.group-configs[3].packages-to-scan[0]=auth.platform.service.log
springdoc.group-configs[4].group=F-监控管理
springdoc.group-configs[4].packages-to-scan[0]=auth.platform.service.monitor
springdoc.group-configs[5].group=G-文件管理
springdoc.group-configs[5].packages-to-scan[0]=auth.platform.service.file
springdoc.group-configs[6].group=H-WS消息管理
springdoc.group-configs[6].packages-to-scan[0]=auth.platform.service.websocket
# 该配置控制是否需要在界面显示过滤框
springdoc.swagger-ui.filter=true
# 该配置主要控制swagger显示是直接展开还是关闭 none 不默认展开  list 列出所有api  full直接展开所有api
springdoc.swagger-ui.doc-expansion=none

5. 访问

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

6. Controller示例

package com.omni.admin.controller;

import com.omni.admin.common.result.ApiResult;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * 接口信息表
 */
@Tag(name = "接口管理")
@RestController
@RequestMapping("/api-info")
public class ApiInfoController {


    @Operation(summary = "测试接口文档")
    @GetMapping("/demo")
    public ApiResult<Void> demo(){
        return ApiResult.success();
    }

}

7. Springdoc-openapi 属性

springdoc-openapi依赖于使用标准文件位置的标准 Spring 配置属性（YML 或属性）。

7.1. Springdoc-OpenAPI 核心属性

7.2. swagger-ui 属性

• 上提供了对 swagger-ui 属性的支持。请参阅官方文档。springdoc-openapi
• 您可以在文档中使用与 Spring 引导属性相同的 swagger-ui 属性。
  

8. Springdoc-openapi 实例

8.1. springdoc 应用实例

8.2 演示应用程序的源代码

https://github.com/springdoc/springdoc-openapi-demos.git

9. 从SpringFox迁移

• 删除 springfox 和 swagger 2 依赖项。改为添加依赖项。springdoc-openapi-ui

 <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.6.14</version> </dependency>

• 将 swagger 2 注释替换为 swagger 3 注释（它已包含在依赖项中）。 招摇 3 注释的包是 .springdoc-openapi-ui``io.swagger.v3.oas.annotations
  • @Api→@Tag
  • @ApiIgnore→或或@Parameter(hidden = true)``@Operation(hidden = true)``@Hidden
  • @ApiImplicitParam→@Parameter
  • @ApiImplicitParams→@Parameters
  • @ApiModel→@Schema
  • @ApiModelProperty(hidden = true)→@Schema(accessMode = READ_ONLY)
  • @ApiModelProperty→@Schema
  • @ApiOperation(value = "foo", notes = "bar")→@Operation(summary = "foo", description = "bar")
  • @ApiParam→@Parameter
  • @ApiResponse(code = 404, message = "foo")→@ApiResponse(responseCode = "404", description = "foo")
• 如果使用对象捕获多个请求查询参数，请使用@ParameterObject
• 此步骤是可选的：仅当您有多个 bean 时，才将它们替换为 bean。Docket``GroupedOpenApi

以前：

 @Bean public Docket publicApi() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.public")) .paths(PathSelectors.regex("/public.*")) .build() .groupName("springshop-public") .apiInfo(apiInfo()); } @Bean public Docket adminApi() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.admin")) .paths(PathSelectors.regex("/admin.*")) .apis(RequestHandlerSelectors.withMethodAnnotation(Admin.class)) .build() .groupName("springshop-admin") .apiInfo(apiInfo()); }

现在：

 @Bean public GroupedOpenApi publicApi() { return GroupedOpenApi.builder() .group("springshop-public") .pathsToMatch("/public/**") .build(); } @Bean public GroupedOpenApi adminApi() { return GroupedOpenApi.builder() .group("springshop-admin") .pathsToMatch("/admin/**") .addMethodFilter(method -> method.isAnnotationPresent(Admin.class)) .build(); }

如果你只有一个 - 删除它，而是将属性添加到你的 ：Docket``application.properties

springdoc.packagesToScan=package1, package2
springdoc.pathsToMatch=/v1, /api/balance/**

 @Bean public OpenAPI springShopOpenAPI() { return new OpenAPI() .info(new Info().title("SpringShop API") .description("Spring shop sample application") .version("v0.0.1") .license(new License().name("Apache 2.0").url("http://springdoc.org"))) .externalDocs(new ExternalDocumentation() .description("SpringShop Wiki Documentation") .url("https://springshop.wiki.github.org/docs")); }