Skip to content

apidoc ​

基于 springdoc 的 OpenAPI 文档界面,替代 Swagger UI 与 knife4j。只替换 UI 层,/v3/api-docs 仍由 springdoc 生成,业务接口与 Swagger 注解不用改。

添加依赖 ​

xml
<dependency>
    <groupId>tech.youlai</groupId>
    <artifactId>apidoc-spring-boot-starter</artifactId>
    <version>0.2.0</version>
</dependency>

springdoc 由项目自己引入,apidoc 只读取它的 /v3/api-docs,不会覆盖宿主版本。

放行路径 ​

使用 Spring Security 时放行三个路径:

yaml
security:
  permit-all-urls:
    - /doc.html
    - /apidoc/**
    - /v3/api-docs/**

配置 ​

yaml
apidoc:
  enabled: true        # false 时不注册入口和静态资源
  path: /doc.html      # 入口路径,资源固定在 /apidoc/ 下

访问 ​

启动后打开 http://localhost:8000/doc.html,服务端直接返回页面,地址栏保持该路径。原有 /swagger-ui.html 不受影响。

二级分组 ​

同一个 tag 下的接口要再分一层,在 tag 名里用 / 分隔,第一段是主分组、其余是二级分组:

java
@Tag(name = "01.认证中心 / 扫码登录")

多个控制器写同一个主分组名会合并到一处。/ 之外也支持 > 和 ::;需要更细粒度时,可在 @Operation 的 extensions 里写 x-group 扩展,单个接口也能成组。

更多 ​

网关聚合、MCP 支持、版本兼容与排序规则见 apidoc 仓库。

基于 MIT 许可发布 · 如需部署协助或二开定制,请查看 支持与合作