API 文档 (api-doc)

最后更新: 1 分钟前

实践版本: v2.16.0

提示文档具有版本时效性，部分内容可能已不适用于当前版本。如发现过时内容，请联系作者进行更新。

简介

continew-starter-api-doc 是 ContiNew Starter 针对接口文档模块的默认实现，底层基于 SpringDoc + NextDoc4j（现代化 API 文档 UI 工具，全面替代 Swagger UI / Knife4j）。

主要特性

默认配置：已预设接口文档通用配置，自动处理静态资源路径映射
增强 UI：基于 NextDoc4j 提供更现代化的接口文档界面，并内置枚举展示、鉴权展示等插件
鉴权配置：支持在配置文件中定义全局接口鉴权规则

快速开始

引入依赖

pom.xml

xml

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

添加配置

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

application.yml

yaml

--- ### 接口文档配置
springdoc:
  api-docs:
    enabled: true
    path: /v3/api-docs
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  # 设置对象型参数的展示形式（设为 true 表示将对象型参数平展开，即对象内的属性直接作为参数展示而不是嵌套在对象内，默认 false）
  # 如果不添加该全局配置，可以在需要如此处理的对象参数类上使用 @ParameterObject
  default-flat-param-object: true
  ## 组件配置
  components:
    # 鉴权配置
    security-schemes:
      Authorization:
        type: HTTP
        in: HEADER
        name: 你的 Token 名称
        scheme: 你的 Token 前缀
## 接口文档增强配置（NextDoc4j）
nextdoc4j:
  enabled: true
  # 启用插件
  plugin:
    # 认证展示插件
    security:
      enabled: true
    # 枚举展示插件
    enum:
      enabled: true

启动应用后，访问 /doc.html 即可查看 NextDoc4j 接口文档界面。

核心依赖

依赖	描述
top.continew.starter:continew-starter-core	核心模块
org.springdoc:springdoc-openapi-starter-webmvc-ui	SpringDoc（OpenAPI 3 集成框架）
top.nextdoc4j:nextdoc4j-spring-boot-starter	NextDoc4j（现代化 API 文档 UI 工具，全面替代 Swagger UI）
top.nextdoc4j:nextdoc4j-plugin-enum	NextDoc4j 枚举展示插件
top.nextdoc4j:nextdoc4j-plugin-security-schemes	NextDoc4j 鉴权展示插件

参考资料

NextDoc4j 官方文档：https://nextdoc4j.top
SpringDoc 官方文档：https://springdoc.org/

API 文档 (api-doc) ​

简介 ​

主要特性 ​

快速开始 ​

引入依赖 ​

添加配置 ​

核心依赖 ​

参考资料 ​