原创 Web开发札记 青衫大叔灬 2023-09-29 00:01 发表于江苏

收录于合集#SpringBoot6个

温馨提示

• Spring Boot 3 只支持OpenAPI3规范

• Knife4j提供的starter已经引用springdoc-openapi的jar，开发者需注意避免jar包冲突

• JDK版本必须 >= 17

一、引入依赖

首先，引用Knife4j的starter,Maven坐标如下：

<properties>
    <knife4j.version>4.3.0</knife4j.version>
</properties>

<dependencies>
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
        <version>${knife4j.version}</version>
    </dependency>
</dependencies>

引入之后，其余的配置，开发者即可完全参考springdoc-openapi的项目说明，Knife4j只提供了增强部分，如果要启用Knife4j的增强功能，可以在配置文件中进行开启。

二、配置详情

部分配置参考如下：

# spring doc
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
    syntax-highlight:
      theme: 'json'
  api-docs:
    path: /v3/api-docs
  # 分组
#  group-configs:
#    - group: 'dev'
#      paths-to-match: '/**'
#    - group: 'prod'
#      paths-to-match: '/prod'
#    - group: 'test'
#      paths-to-match: '/test'

# Knife4j增强配置
knife4j:
  enable: true
  setting:
    language: zh_cn
    swagger-model-name: '对象模型'
    enable-swagger-models: true
    enable-dynamic-parameter: false
    footer-custom-content: "<strong>Copyright ©️ 2023 XXX. All Rights Reversed</strong>"
    enable-footer-custom: true
    enable-footer: true
    enable-document-manage: true

三、个性化定制

针对一些其他的配置，我们仍然可以参考OpenAPI2.0进行调整，我们也可以直接去Spring Doc项目去查看相关文档进行一些个性化配置，部分配置参考如下：

import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;
import org.springframework.context.annotation.PropertySource;
@Configuration
@Primary
@PropertySource("classpath:springdoc.properties")
public class SpringDocConfig {

    @Value("${termsOfService}")
    private String termsOfService;

    @Value("${title}")
    private String title;

    @Value("${description}")
    private String description;

    @Value("${version}")
    private String version;

    @Value("${contact.name}")
    private String contactName;

    @Value("${contact.url}")
    private String contactUrl;

    @Value("${contact.email}")
    private String contactEmail;

    @Value("${license.name}")
    private String licenseName;

    @Value("${license.url}")
    private String licenseUrl;

    @Value("${external.url}")
    private String externalUrl;

    @Value("${external.description}")
    private String externalDescription;

    @Value("${group.dev.name}")
    private String devGroupName;

    @Value("${group.test.name}")
    private String testGroupName;

    @Value("${group.proc.name}")
    private String procGroupName;

    @Value("${group.dev.path}")
    private String devGroupPath;

    @Value("${group.test.path}")
    private String testGroupPath;

    @Value("${group.proc.path}")
    private String procGroupPath;

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title(title)
                        .description(description)
                        .version(version)
                        .contact(new Contact()
                                .name(contactName)
                                .url(contactUrl)
                                .email(contactEmail))
                        .termsOfService(termsOfService)
                        .license(new License()
                                .name(licenseName)
                                .url(licenseUrl)))
                .externalDocs(new ExternalDocumentation()
                        .description(externalDescription)
                        .url(externalUrl));
    }

    @Bean
    public GroupedOpenApi devApi() {
        return GroupedOpenApi.builder()
                .group(devGroupName)
                .pathsToMatch(devGroupPath)
                .build();
    }

    @Bean
    public GroupedOpenApi testApi() {
        return GroupedOpenApi.builder()
                .group(testGroupName)
                .pathsToMatch(testGroupPath)
                .build();
    }

    @Bean
    public GroupedOpenApi prodApi() {
        return GroupedOpenApi.builder()
                .group(procGroupName)
                .pathsToMatch(procGroupPath)
                .build();
    }
}

具体的参数我抽离成了properties文件中，方便维护修改对应的参数：

# 服务声明
termsOfService=1.服务提供方：本条款中的“服务提供方”指指定的公司或组织，提供API服务。<br>\
  2.用户：本条款中的“用户”指使用服务提供方提供的API服务的个人、公司或组织。<br>\
  3.授权：用户在遵守本条款的前提下，服务提供方授予用户使用其API服务的权利。<br>\
  4.使用限制：用户在使用API服务时，必须遵守以下限制：<br>\
  &nbsp;&nbsp;&nbsp;&nbsp;a.用户不得使用API服务进行非法活动或违反法律法规的行为；<br>\
  &nbsp;&nbsp;&nbsp;&nbsp;b.用户不得以任何方式干扰、破坏或损害API服务的正常运行；<br>\
  &nbsp;&nbsp;&nbsp;&nbsp;c.用户不得滥用API服务，包括但不限于超出使用限制、恶意攻击等行为；<br>\
  &nbsp;&nbsp;&nbsp;&nbsp;d.用户不得将API服务用于未经授权的商业用途。<br>\
  5.账户安全：用户在使用API服务时，必须保护其账户的安全性，包括但不限于保护密码和API密钥的安全。<br>\
  6.责任限制：服务提供方对于用户使用API服务所导致的任何直接或间接损失不承担责任，包括但不限于利润损失、数据损失等。<br>\
  7.服务变更和终止：服务提供方有权根据需要随时变更或终止API服务，用户在此不得要求服务提供方承担任何责任。<br>\
  8.知识产权：服务提供方保留所有API服务相关的知识产权。<br>9.隐私保护：服务提供方将根据相关法律法规保护用户的个人信息和数据隐私。<br>\
  10.争议解决：本条款的解释和适用以及由此产生的争议应适用服务提供方所在地的法律。<br>\
  11.其他条款：本条款中的任何条款无效或不可执行时，不影响其他条款的效力。<br>\
  12.条款变更：服务提供方有权随时修改本条款，并通过适当的方式向用户通知。<br>\
  📢请用户在使用API服务之前仔细阅读并理解本条款，如用户不同意本条款的任何内容，请勿使用API服务。<br>\
  ⚠️用户一旦使用API服务，即视为用户已接受本条款的全部内容。

# 标题
title = HUB-BOOT API（开发文档）

# 描述
description = HUB-BOOT 开发文档

# 版本
version = beta-v1.0.1

# 联系方式
contact.name = 蔡熙贝
contact.url = https://gitee.com/caixibei
contact.email = caixibei@139.com

# 协议
license.name = Apache 2.0
license.url = https://gitee.com/caixibei

# 附加信息
external.url = https://gitee.com/caixibei/hub-boot/wikis
external.description = HUB-BOOT Wiki文档

# 分组信息
group.dev.name = 开发环境
group.dev.path = /**
group.test.name = 测试环境
group.test.path = /test/**
group.proc.name = 生产环境
group.proc.path = /proc/**

四、访问说明

最后，访问Knife4j的文档地址：http://ip:port/doc.html 即可查看文档。