接口文档

pom依赖

xml

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
    <version>4.3.0</version>
</dependency>

配置

java

import cn.diyai.config.properties.OpenApiProperties;
import io.swagger.v3.oas.models.ExternalDocumentation;
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.media.StringSchema;
import io.swagger.v3.oas.models.parameters.HeaderParameter;
import io.swagger.v3.oas.models.parameters.Parameter;
import org.springdoc.core.GroupedOpenApi;
import org.springdoc.core.customizers.OperationCustomizer;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    private static String AUTH_PACKAGE = "cn.diyai.auth";
    private static String TOKEN_NAME = "Authorization";
    private static String SYSTEM_PACKAGE = "cn.diyai.system";
    private static String USER_PACKAGE = "cn.diyai.user";
    private static String COMMON_PACKAGE = "cn.diyai.common";
    private static String GENERATOR_PACKAGE = "cn.diyai.generator";


    @Autowired
    private OpenApiProperties openApiProperties;
    /**
     * token请求头参数
     */
    private Parameter tokenParameter = new HeaderParameter().name(TOKEN_NAME).required(false).schema(new StringSchema()._default("").name(TOKEN_NAME));


    @Bean
    public OpenAPI openApi() {
        return new OpenAPI()
                .info(new Info()
                        .title(openApiProperties.getTitle())
                        .description(openApiProperties.getDescription())
                        .termsOfService(openApiProperties.getTermsOfService())
                        .contact(new Contact().name(openApiProperties.getContactName()).url(openApiProperties.getContactUrl()).email(openApiProperties.getContactEmail()))
                        .version(openApiProperties.getVersion()))
                .externalDocs(new ExternalDocumentation().description(openApiProperties.getExternalDescription()).url(openApiProperties.getExternalUrl()));
    }


    @Bean
    public GroupedOpenApi authApi() {
        String[] packagedToMatch = {AUTH_PACKAGE};
        return api("2.登录授权接口文档", packagedToMatch);
    }

    @Bean
    public GroupedOpenApi adminApi() {
        String[] packagedToMatch = {SYSTEM_PACKAGE};
        return api("3.系统管理接口文档", packagedToMatch);
    }

    @Bean
    public GroupedOpenApi userApi() {
        String[] packagedToMatch = {USER_PACKAGE};
        return api("4.App用户模块接口文档", packagedToMatch);
    }

    @Bean
    public GroupedOpenApi commonApi() {
        String[] packagedToMatch = {COMMON_PACKAGE};
        return api("5.公共服务接口文档", packagedToMatch);
    }

    @Bean
    public GroupedOpenApi generatorApi() {
        String[] packagedToMatch = {GENERATOR_PACKAGE};
        return api("6.生成代码接口文档", packagedToMatch);
    }

    /**
     * 除了上面的接口之外，其它的接口都在项目接口文档中
     * 请根据实际情况进行自定义
     *
     * @return
     */
    @Bean
    public GroupedOpenApi projectApi() {
        return GroupedOpenApi.builder()
                .group("1.项目接口文档")
                .addOperationCustomizer(getOperationCustomizer())
                .pathsToMatch("/**")
                .packagesToExclude(AUTH_PACKAGE, SYSTEM_PACKAGE, USER_PACKAGE, COMMON_PACKAGE, GENERATOR_PACKAGE)
                .build();
    }

    /**
     * 配置接口
     *
     * @param group
     * @param packagedToMatch
     * @return
     */
    private GroupedOpenApi api(String group, String[] packagedToMatch) {
        return GroupedOpenApi.builder()
                .group(group)
                .addOperationCustomizer(getOperationCustomizer())
                .pathsToMatch("/**")
                .packagesToScan(packagedToMatch).build();
    }

    /**
     * 配置自定义请求头
     *
     * @return
     */
    public OperationCustomizer getOperationCustomizer() {
        return (operation, handlerMethod) -> {
            operation.addParametersItem(tokenParameter);
            return operation;
        };
    }

}

属性配置

java

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

/**
 * Swagger属性配置
 */
@Data
@Component
@ConfigurationProperties(prefix = "openapi")
public class OpenApiProperties {

    /**
     * 标题
     */
    private String title;

    /**
     * 描述
     */
    private String description;

    /**
     * 团队地址
     */
    private String termsOfService;

    /**
     * 联系人名称
     */
    private String contactName;

    /**
     * 联系人URL
     */
    private String contactUrl;

    /**
     * 联系人Email
     */
    private String contactEmail;

    /**
     * 版本
     */
    private String version;

    /**
     * 扩展描述
     */
    private String externalDescription;

    /**
     * 扩展Url
     */
    private String externalUrl;

}

配置yml

yaml

openapi:
  title: IT技术进阶
  description: IT技术进阶
  terms-of-service: https://diyai.cn
  contact-name: Patrick
  contact-url: https://diyai.cn
  contact-email: wxmgcs@foxmail.com
  version: 1.0
  external-description: IT技术进阶
  external-url: https://diyai.cn

# swagger配置
springdoc:
  swagger-ui:
    enabled: true

knife4j:
  enable: true
  basic:
    enable: true
    # 启用账号密码登录
    username: admin
    password: 123456
  setting:
    # 自定义底部
    enable-footer: true
    enable-footer-custom: true
    footer-custom-content: MIT License | Copyright © 2023-2024 [diyai](https://diyai.cn)

接口文档 ​

pom依赖 ​

配置 ​

属性配置 ​

配置yml ​

接口文档

pom依赖

配置

属性配置

配置yml