回显
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 工程开发
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# golang-echo-oapi
## When To Use
- Use this skill for changes to `github.com/adlandh/echo-oapi-middleware/v2` or code that consumes this library.
- Apply it when touching `SwaggerYaml`, `SwaggerYamlWithConfig`, `SwaggerUI`, `SwaggerUIWithConfig`, their tests, or README examples.
## Library Shape
- Package name is `echooapimiddleware`; it is a single-package Go module with no generated code or subpackages.
- It targets Go 1.25 and Echo v5 (`github.com/labstack/echo/v5`). Echo handlers use `func(c *echo.Context) error`.
- Public API accepts `*openapi3.T` from `github.com/getkin/kin-openapi/openapi3`; do not add runtime parsing as part of the middleware path unless explicitly requested.
## Behavior To Preserve
- Serialize the OpenAPI spec once when middleware is created, not on every request.
- `SwaggerYaml` defaults to `/swagger.yaml` and serves only `GET` and `HEAD`; all other methods and paths pass through to the next handler.
- `SwaggerUI` defaults to `/swagger`, also serves `/swagger/` and `/swagger/index.html`, and wires the YAML endpoint.
- `HEAD` responses for YAML and UI must set `Content-Length` and write no body.
- `nil` specs are valid and produce successful empty YAML responses.
- `KeepServers` defaults to false: omit top-level `servers` from emitted YAML without mutating the caller's `*openapi3.T`.
- Generated Swagger UI HTML references unpkg `swagger-ui-dist@5` assets.
## Verification Commands
- Fast local check: `go test ./...`.
- CI-equivalent tests: `go test -race -coverprofile=coverage.txt -covermode=atomic ./...`.
- Focused tests: `go test -run TestSwaggerYaml_RequestRouting .` or `go test -run TestSwaggerUI_DefaultPaths .`.
- Benchmark YAML serving path: `go test -bench BenchmarkSwaggerYamlGET -benchmem .`.
- CI lint downloads the shared config before running: `curl -sS https://raw.githubusercontent.com/adlandh/golangci-lint-config/refs/heads/main/.golangci.yml -o .golangci.yml`, then `golangci-lint run`.
## Implementation Notes
- Keep the middleware chain passthrough behavior explicit; tests depend on non-matching requests reaching downstream Echo routes.
- Prefer small direct functions over new abstractions; this library is intentionally tiny.
- If changing config defaults or route matching, update both README examples and tests in the same change.
## Integrating Into A Project
- **Do not try to embed or parse `swagger.yaml` / `openapi.yaml` at runtime.** This library accepts `*openapi3.T` from `github.com/getkin/kin-openapi/openapi3`, not a raw YAML file.
- Before reaching for `//go:embed` or `os.ReadFile`, check the generated code — most OpenAPI code generators (e.g. `oapi-codegen`) produce a `GetSpec` function that returns the parsed `*openapi3.T` directly. Pass that to `SwaggerYAML` or `SwaggerUI`.
---
> Source: [adlandh/echo-oapi-middleware](https://github.com/adlandh/echo-oapi-middleware) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->
章节与文件索引
按说明文件中的顺序排列。
何时使用
图书馆形状
保持行为
验证命令
实施说明
文件/命令 -> github.com/adlandh/echo-oapi-middleware/v2 · SwaggerYaml · SwaggerYamlWithConfig · SwaggerUI · SwaggerUIWithConfig · echooapimiddleware · github.com/labstack/echo/v5 · func(c *echo.Context) error
内容校验值 -> 771aa9fc9a9b
当前原文的自动摘译,尚未人工审校。
何时使用
使用此技能来更改
github.com/adlandh/echo-oapi-middleware/v2或使用此库的代码。在接触SwaggerYaml、SwaggerYamlWithConfig、SwaggerUI、SwaggerUIWithConfig、它们的测试或 README 示例时应用它。图书馆形状
软件包名称为
echooapimiddleware;它是一个单包 Go 模块,没有生成代码或子包。它的目标是 Go 1.25 和 Echo v5 (github.com/labstack/echo/v5)。回声处理程序使用func(c *echo.Context) error。公共API接受来自github.com/getkin/kin-openapi/openapi3的*openapi3.T;除非明确请求,否则不要将运行时解析添加为中间件路径的一部分。保持行为
在创建中间件时序列化 OpenAPI 规范一次,而不是在每次请求时序列化。
SwaggerYaml默认为/swagger.yaml,仅服务于GET和HEAD;所有其他方法和路径都会传递到下一个处理程序。SwaggerUI默认为/swagger,还提供/swagger/和/swagger/index.html,并连接YAML端点。 YAML 和 UI 的HEAD响应必须设置Content-Length并且不写入正文。验证命令
快速本地检查:
go test ./...。 CI 等效测试:go test -race -coverprofile=coverage.txt -covermode=atomic ./...。重点测试:go test -run TestSwaggerYaml_RequestRouting .或go test -run TestSwaggerUI_DefaultPaths .。基准 YAML 服务路径:go test -bench BenchmarkSwaggerYamlGET -benchmem .。 CI lint 在运行之前下载共享配置:curl -sS https://raw.githubusercontent.com/adlandh/golangci-lint-config/refs/heads/main/.golangci.yml -o .golangci.yml,然后是golangci-lint run。实施说明
保持中间件链直通行为明确;测试取决于到达下游 Echo 路由的不匹配请求。比起新的抽象,更喜欢小的直接函数;这个图书馆故意很小。如果更改配置默认值或路由匹配,请在同一更改中更新自述文件示例和测试。