feat: add OpenAPI specification#159
Merged
Merged
Conversation
|
Very nice addition! 🙌 However, I wonder if the whoami app could expose the openapi.yaml on a path, eg. |
Contributor
Author
|
@immanuelfodor Love this idea. Since the spec already lives at the repo root, it could be embedded at build time with //go:embed and served directly. Then it can be registered alongside the other routes in main(). |
Contributor
Author
|
i've implemented this in the PR: 99bb044 |
sheddy-traefik
changed the title
sheddy-traefik
changed the title
|
FYI, CI is failing |
Contributor
Author
Yeah @immanuelfodor the issue is with golanglint, the version it uses doesn't support Go v1.26 and its pinned. |
jspdown
reviewed
Jul 1, 2026
golangci-lint v2.1.2 is built with go1.24 and panics parsing the go1.26 stdlib that the 'stable' toolchain now installs. Bump to v2.12.2 (built with go1.26) and disable the newly-added linters (iotamixing, noinlineerr, wsl_v5) to keep the existing style rules.
The pinned master install.sh currently resolves the wrong release asset (downloads the .sbom.json instead of the tarball), so its checksum verification fails deterministically. Install through the Go module proxy instead, which is not subject to GitHub asset resolution or rate limiting.
jspdown
approved these changes
Jul 1, 2026
ldez
reviewed
Jul 1, 2026
| - name: Install golangci-lint ${{ env.GOLANGCI_LINT_VERSION }} | ||
| run: | | ||
| curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin ${GOLANGCI_LINT_VERSION} | ||
| go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@${GOLANGCI_LINT_VERSION} |
Contributor
There was a problem hiding this comment.
Suggested change
| go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@${GOLANGCI_LINT_VERSION} | |
| curl -sSfL https://golangci-lint.run/install.sh | sh -s -- -b $(go env GOPATH)/bin ${GOLANGCI_LINT_VERSION} |
- https://golangci-lint.run/docs/welcome/install/local/#binaries
- https://golangci-lint.run/docs/welcome/install/local/#install-from-sources
Or
- uses: golangci/golangci-lint-action@v9
with:
version: ${{ env.GOLANGCI_LINT_VERSION }}
install-only: 'true'
There was a problem hiding this comment.
Even better with the GH action. Thanks @ldez
LBF38
approved these changes
Jul 1, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
6 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds an
openapi.yaml(OpenAPI 3.0.3) at the repository root describing whoami's HTTP API, and serves it atGET /openapi.yaml.Why
whoami is widely used as a demo backend (including throughout the Traefik Hub and Traefik Proxy docs), but it ships no machine-readable API description. A spec makes it usable as a ready-made example for API gateways, portals, mock servers, and client generators without everyone hand-rolling their own.
Serving it directly from whoami means consumers get the spec from the same endpoint they are already routing to, with no additional infrastructure needed.
Details
The spec is hand-written against
app.goand covers the HTTP handlers:GET /— request info as plain text (wait,envquery params)GET /api— request info as JSON (theDatastruct, incl.remoteAddrandenviron)GET /bench— returns1GET /data— sized payload (size,unit,attachment)GET /health/POST /health— read and set the health status codeGET /openapi.yaml— serves this spec (embedded at build time via//go:embed)The
/echoWebSocket endpoint and the/whoami.Whoami/gRPC service are intentionally omitted, since neither is expressible in OpenAPI; this is noted in the spec'sinfo.description.