golang-echo-oapi

Engineering Community

Repo stars 0
Author repo skills-registry

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: Use when working on github.com/adlandh/echo-oapi-middleware/v2, an Echo v5 middleware library that serves OpenAPI YAML and Swagg…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “When To Use”, “Library Shape”, “Behavior To Preserve”, “Verification Commands”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name golang-echo-oapi directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “When To Use / Library Shape / Behavior To Preserve” before expanding.

Boundaries And Review

Dependencies: It usually needs no extra API key, so start with a small validation task.
Permissions: Declared permissions include read / write; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

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 — distributed by TomeVault.

Fluxly profile Author and license come from source; runtime, permissions, and network are Fluxly detections or estimates

Fluxly category: 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
Author / version / license: @tomevault-io · no license declared
Fluxly token estimate: Lean
Fluxly setup estimate: Plug-and-play
External API key: No requirement detected
Detected OS requirements: Unspecified
Runtime requirements: Unspecified
Detected file/system behavior: Read-only
Write / modify
Detected network behavior: External requests
Install commands: None (reference only)

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。

Output preview golang-echo-oapi.preview

The current SKILL.md does not define a fixed output example.

SKILL.md 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 .`.

…

Evidence boundary and execution chain

Author text anchors workflow facts; Fluxly only indexes current sections, terms, files, and commands.

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

Decide Fit First

Design Intent

How To Use It

Boundaries And Review

golang-echo-oapi

When To Use

Library Shape

Behavior To Preserve

Verification Commands

Implementation Notes

Integrating Into A Project

Discussion