golang echo oapi
- Repo stars 0
- Author repo skills-registry
- Domain
- Engineering
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @tomevault-io · no license declared
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Network behavior
- External requests
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# 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 -->
Sections and files
Listed in source order.
sections -> When To Use → Library Shape → Behavior To Preserve → Verification Commands → Implementation Notes → Integrating Into A Project
terms -> Do not try to embed or parse swagger.yaml / openapi.yaml at runtime.
files/cmd -> github.com/adlandh/echo-oapi-middleware/v2 · SwaggerYaml · SwaggerYamlWithConfig · SwaggerUI · SwaggerUIWithConfig · echooapimiddleware · github.com/labstack/echo/v5 · func(c *echo.Context) error
body sha256 -> 771aa9fc9a9b
When To Use
Use this skill for changes to
github.com/adlandh/echo-oapi-middleware/v2or code that consumes this library. Apply it when touchingSwaggerYaml,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 usefunc(c *echo.Context) error. Public API accepts*openapi3.Tfromgithub.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.
SwaggerYamldefaults to/swagger.yamland serves onlyGETandHEAD; all other methods and paths pass through to the next handler.SwaggerUIdefaults to/swagger, also serves/swagger/and/swagger/index.html, and wires the YAML endpoint.HEADresponses for YAML and UI must setContent-Lengthand write no body.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 .orgo 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, thengolangci-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.