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 仓库。
