API 文档 (api-doc)

最后更新: 16 天前

实践版本: v2.13.4

简介

continew-starter-api-doc 是 ContiNew Starter 针对接口文档模块的默认实现，底层基于 Knife4j（前身是 swagger-bootstrap-ui）。

主要特性

• 默认配置：已预设接口文档通用配置，自动处理静态资源路径映射（/favicon.ico、/doc.html、/webjars/**）
• 鉴权配置：支持在配置文件中定义全局接口鉴权规则

快速开始

引入依赖

pom.xml

<dependency>
    <groupId>top.continew.starter</groupId>
    <artifactId>continew-starter-api-doc</artifactId>
</dependency>

添加配置

配置详情请参考类 top.continew.starter.apidoc.autoconfigure.SpringDocAutoConfiguration。

application.yml

--- ### 接口文档配置
springdoc:
  api-docs:
    enabled: true
    path: /v3/api-docs
  swagger-ui:
    enabled: true
    path: /swagger-ui
  # 设置对象型参数的展示形式（设为 true 表示将对象型参数平展开，即对象内的属性直接作为参数展示而不是嵌套在对象内，默认 false）
  # 如果不添加该全局配置，可以在需要如此处理的对象参数类上使用 @ParameterObject
  default-flat-param-object: true
  ## 组件配置
  components:
    # 鉴权配置
    security-schemes:
      Authorization:
        type: HTTP
        in: HEADER
        name: 你的 Token 名称
        scheme: 你的 Token 前缀
## 接口文档增强配置
knife4j:
  enable: true
  setting:
    # 是否显示默认的 footer（默认 true，显示）
    enable-footer: false
    # 是否自定义 footer（默认 false，非自定义）
    enable-footer-custom: true
    # 自定义 footer 内容，支持 Markdown 语法
    footer-custom-content: 'Copyright © 2022-present ContiNew Starter'

核心依赖

依赖	描述
top.continew.starter:continew-starter-core	核心模块
com.github.xiaoymin:knife4j-openapi3-jakarta-spring-boot-starter	Knife4j（前身是 swagger-bootstrap-ui，集 Swagger2 和 OpenAPI3 为一体的增强解决方案）

参考资料

1. Knife4j 官方文档：https://doc.xiaominfo.com/docs/quick-start