/swagger/index.html 提供交互式 Swagger UI。它需要在两个层面上显式启用:二进制文件必须使用 swagger 构建标签编译,并且运行时必须设置 SWAGGER_ENABLED。
为什么默认构建中不包含它
Release 二进制文件和官方 Docker 镜像在构建时不带swagger 标签。内嵌的规范和 UI 资源会使二进制文件增大 30 MB 以上(在未剥离符号的构建中大约从 55 MB 增至 88 MB),镜像也会相应增大,而生产环境中很少需要该端点。不包含它可以让构建产物保持精简,并将暴露面降到最低。
如果您只需要 API 规范,可以改为在任意 OpenAPI 查看器中使用仓库中的 docs/openapi.json。
带 Swagger 构建
make run 会带上该标签进行构建,并在本地开发时自动启用 UI。
运行时启用
config.yaml 中设置:
BASE_PATH 设置。如果在未带该标签构建的二进制文件上设置了 SWAGGER_ENABLED=true,GoModel 会在启动时记录一条警告,并且 /swagger/* 不提供任何内容。
重新生成规范
修改 API 注解后,运行make swagger 以重新生成内嵌的 docs 包和 docs/openapi.json。详情请参阅 DEVELOPMENT.md。