回显

工程开发 社区

技能解读

当前原文的自动摘译,尚未人工审校。

何时使用

使用此技能来更改 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 路由的不匹配请求。比起新的抽象,更喜欢小的直接函数;这个图书馆故意很小。如果更改配置默认值或路由匹配,请在同一更改中更新自述文件示例和测试。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
工程开发
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@tomevault-io · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
即装即用
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
网络行为
允许外网请求
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# 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 Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。