yys 增加接口文档

maven

2 天以前 3b9d4ccc8283d44b9eea0a44479b4c928f644e1e

yys  增加接口文档

 ruoyi-admin/pom.xml

@@ -16,7 +16,12 @@
    </description>

    <dependencies>

        <!-- ruoyi-springboot2 / swagger knife4j é…ç½® -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
            <version>4.4.0</version>
        </dependency>
        <!-- spring-boot-devtools -->
        <dependency>
            <groupId>org.springframework.boot</groupId>

 ruoyi-admin/src/main/java/com/ruoyi/web/core/config/SwaggerConfig.java

@@ -1,64 +1,157 @@
package com.ruoyi.web.core.config;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import com.ruoyi.common.config.RuoYiConfig;
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.media.StringSchema;
import io.swagger.v3.oas.models.parameters.Parameter;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import io.swagger.v3.oas.models.security.SecurityScheme.In;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import org.springdoc.core.customizers.OpenApiBuilderCustomizer;
import org.springdoc.core.customizers.ServerBaseUrlCustomizer;
import org.springdoc.core.models.GroupedOpenApi;
import org.springdoc.core.properties.SpringDocConfigProperties;
import org.springdoc.core.providers.JavadocProvider;
import org.springdoc.core.service.OpenAPIService;
import org.springdoc.core.service.SecurityService;
import org.springdoc.core.utils.PropertyResolverUtils;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpHeaders;

/**
 * Swagger2的接口配置
 * Swagger è‡ªåŠ¨é…ç½®ç±»ï¼ŒåŸºäºŽ OpenAPI + Springdoc å®žçŽ°ã€‚
 * 
 * @author ruoyi
 * å‹æƒ…提示：
 * 1. Springdoc æ–‡æ¡£åœ°å€ï¼š<a href="https://github.com/springdoc/springdoc-openapi">仓库</a>
 * 2. Swagger è§„范，于 2015 æ›´åä¸º OpenAPI è§„范，本质是一个东西
 *
 */
// @AutoConfiguration
@Configuration
@ConditionalOnClass({OpenAPI.class})
@EnableConfigurationProperties(SwaggerProperties.class)
@ConditionalOnProperty(prefix = "springdoc.api-docs", name = "enabled", havingValue = "true", matchIfMissing = true) // è®¾ç½®ä¸º false æ—¶ï¼Œç¦ç”¨
public class SwaggerConfig
{
    /** ç³»ç»ŸåŸºç¡€é…ç½® */
    @Autowired
    private RuoYiConfig ruoyiConfig;
    
    /**
     * è‡ªå®šä¹‰çš„ OpenAPI å¯¹è±¡
     */
    @Bean
    public OpenAPI customOpenApi()
    {
        return new OpenAPI().components(new Components()
            // è®¾ç½®è®¤è¯çš„请求头
            .addSecuritySchemes("apikey", securityScheme()))
            .addSecurityItem(new SecurityRequirement().addList("apikey"))
            .info(getApiInfo());
    }
    public static final String HEADER_TENANT_ID = "tenant-id";


    // ========== å…¨å±€ OpenAPI é…ç½® ==========
    
    @Bean
    public SecurityScheme securityScheme()
    {
        return new SecurityScheme()
            .type(SecurityScheme.Type.APIKEY)
            .name("Authorization")
            .in(SecurityScheme.In.HEADER)
            .scheme("Bearer");
    public OpenAPI createApi(SwaggerProperties properties) {
        Map<String, SecurityScheme> securitySchemas = buildSecuritySchemes();
        OpenAPI openAPI = new OpenAPI()
                // æŽ¥å£ä¿¡æ¯
                .info(buildInfo(properties))
                // æŽ¥å£å®‰å…¨é…ç½®
                .components(new Components().securitySchemes(securitySchemas))
                .addSecurityItem(new SecurityRequirement().addList(HttpHeaders.AUTHORIZATION));
        securitySchemas.keySet().forEach(key -> openAPI.addSecurityItem(new SecurityRequirement().addList(key)));
        return openAPI;
    }
    
    /**
     * æ·»åŠ æ‘˜è¦ä¿¡æ¯
     * API æ‘˜è¦ä¿¡æ¯
     */
    public Info getApiInfo()
    {
    private Info buildInfo(SwaggerProperties properties) {
        return new Info()
            // è®¾ç½®æ ‡é¢˜
            .title("标题：若依管理系统_接口文档")
            // æè¿°
            .description("描述：用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...")
            // ä½œè€…信息
            .contact(new Contact().name(ruoyiConfig.getName()))
            // ç‰ˆæœ¬
            .version("版本号:" + ruoyiConfig.getVersion());
                .title(properties.getTitle())
                .description(properties.getDescription())
                .version(properties.getVersion())
                .contact(new Contact().name(properties.getAuthor()).url(properties.getUrl()).email(properties.getEmail()))
                .license(new License().name(properties.getLicense()).url(properties.getLicenseUrl()));
    }

    /**
     * å®‰å…¨æ¨¡å¼ï¼Œè¿™é‡Œé…ç½®é€šè¿‡è¯·æ±‚头 Authorization ä¼ é€’ token å‚æ•°
     */
    private Map<String, SecurityScheme> buildSecuritySchemes() {
        Map<String, SecurityScheme> securitySchemes = new HashMap<>();
        SecurityScheme securityScheme = new SecurityScheme()
                .type(SecurityScheme.Type.APIKEY) // ç±»åž‹
                .name(HttpHeaders.AUTHORIZATION) // è¯·æ±‚头的 name
                .in(SecurityScheme.In.HEADER); // token æ‰€åœ¨ä½ç½®
        securitySchemes.put(HttpHeaders.AUTHORIZATION, securityScheme);
        return securitySchemes;
    }

    /**
     * è‡ªå®šä¹‰ OpenAPI å¤„理器
     */
    @Bean
    public OpenAPIService openApiBuilder(Optional<OpenAPI> openAPI,
                                         SecurityService securityParser,
                                         SpringDocConfigProperties springDocConfigProperties,
                                         PropertyResolverUtils propertyResolverUtils,
                                         Optional<List<OpenApiBuilderCustomizer>> openApiBuilderCustomizers,
                                         Optional<List<ServerBaseUrlCustomizer>> serverBaseUrlCustomizers,
                                         Optional<JavadocProvider> javadocProvider) {

        return new OpenAPIService(openAPI, securityParser, springDocConfigProperties,
                propertyResolverUtils, openApiBuilderCustomizers, serverBaseUrlCustomizers, javadocProvider);
    }

    // ========== åˆ†ç»„ OpenAPI é…ç½® ==========

    /**
     * æ‰€æœ‰æ¨¡å—çš„ API åˆ†ç»„
     */
    @Bean
    public GroupedOpenApi allGroupedOpenApi() {
        return buildGroupedOpenApi("all", "");
    }

    public static GroupedOpenApi buildGroupedOpenApi(String group) {
        return buildGroupedOpenApi(group, group);
    }

    public static GroupedOpenApi buildGroupedOpenApi(String group, String path) {
        return GroupedOpenApi.builder()
                .group(group)
                .pathsToMatch("/admin-api/" + path + "/**", "/app-api/" + path + "/**", "/**")
                .addOperationCustomizer((operation, handlerMethod) -> operation
                        // .addParametersItem(buildTenantHeaderParameter())
                        .addParametersItem(buildSecurityHeaderParameter()))
                .build();
    }

    /**
     * æž„建 Authorization è®¤è¯è¯·æ±‚头参数
     *
     * è§£å†³ Knife4j <a href="https://gitee.com/xiaoym/knife4j/issues/I69QBU">Authorize æœªç”Ÿæ•ˆï¼Œè¯·æ±‚header里未包含参数</a>
     *
     * @return è®¤è¯å‚æ•°
     */
    private static Parameter buildSecurityHeaderParameter() {
        return new Parameter()
                .name(HttpHeaders.AUTHORIZATION) // header å
                .description("认证 Token") // æè¿°
                .in(String.valueOf(SecurityScheme.In.HEADER)) // è¯·æ±‚ header
                .schema(new StringSchema()._default("Bearer test1").name(HEADER_TENANT_ID).description("认证 Token")); // é»˜è®¤ï¼šä½¿ç”¨ç”¨æˆ·ç¼–号为 1
    }

    /**
     * æž„建 Tenant ç§Ÿæˆ·ç¼–号请求头参数
     * @return å¤šç§Ÿæˆ·å‚æ•°
     */
/*   private static Parameter buildTenantHeaderParameter() {
    return new Parameter()
        .name(HEADER_TENANT_ID) // header å
        .description("租户编号") // æè¿°
        .in(String.valueOf(SecurityScheme.In.HEADER)) // è¯·æ±‚ header
        .schema(new IntegerSchema()._default(1L).name(HEADER_TENANT_ID).description("租户编号")); // é»˜è®¤ï¼šä½¿ç”¨ç§Ÿæˆ·ç¼–号为 1
  } */
}

 ruoyi-admin/src/main/java/com/ruoyi/web/core/config/SwaggerProperties.java

¶Ô±ÈÐÂÎļþ
@@ -0,0 +1,63 @@
package com.ruoyi.web.core.config;


import jakarta.validation.constraints.NotEmpty;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
/**
 * @author :yys
 * @date : 2025/8/22 9:16
 */



/**
 * Swagger é…ç½®å±žæ€§*/
@ConfigurationProperties("aixin.swagger")
@Data
public class SwaggerProperties {

    /**
     * æ ‡é¢˜
     */
    @NotEmpty(message = "标题不能为空")
    private String title;
    /**
     * æè¿°
     */
    @NotEmpty(message = "描述不能为空")
    private String description;
    /**
     * ä½œè€…
     */
    @NotEmpty(message = "作者不能为空")
    private String author;
    /**
     * ç‰ˆæœ¬
     */
    @NotEmpty(message = "版本不能为空")
    private String version;
    /**
     * url
     */
    @NotEmpty(message = "扫描的 package ä¸èƒ½ä¸ºç©º")
    private String url;
    /**
     * email
     */
    @NotEmpty(message = "扫描的 email ä¸èƒ½ä¸ºç©º")
    private String email;

    /**
     * license
     */
    @NotEmpty(message = "扫描的 license ä¸èƒ½ä¸ºç©º")
    private String license;

    /**
     * license-url
     */
    @NotEmpty(message = "扫描的 license-url ä¸èƒ½ä¸ºç©º")
    private String licenseUrl;

}

 ruoyi-framework/src/main/java/com/ruoyi/framework/config/ResourcesConfig.java

@@ -55,6 +55,7 @@
    public CorsFilter corsFilter()
    {
        CorsConfiguration config = new CorsConfiguration();
        config.setAllowCredentials(true);
        // è®¾ç½®è®¿é—®æºåœ°å€
        config.addAllowedOriginPattern("*");
        // è®¾ç½®è®¿é—®æºè¯·æ±‚头

 ruoyi-framework/src/main/java/com/ruoyi/framework/config/SecurityConfig.java

@@ -114,7 +114,7 @@
                requests.requestMatchers("/login", "/register", "/captchaImage").permitAll()
                    // é™æ€èµ„源，可匿名访问
                    .requestMatchers(HttpMethod.GET, "/", "/*.html", "/**.html", "/**.css", "/**.js", "/profile/**").permitAll()
                    .requestMatchers("/swagger-ui.html", "/v3/api-docs/**", "/swagger-ui/**", "/druid/**").permitAll()
                    .requestMatchers("/swagger-ui.html", "/v3/api-docs/**", "/swagger-ui/**","/swagger-resources", "/druid/**","/swagger-resources","/webjars/**", "/favicon.ico", "/doc.html").permitAll()
                    // é™¤ä¸Šé¢å¤–的所有请求全部需要鉴权认证
                    .anyRequest().authenticated();
            })