refactor(codegen): better Swagger compression, modern naming (#1909)
* refactor(codegen): better Swagger compression
* test(compatibility): Regenerate test spec
* Add GetSpec/GetSpecJSON; revert const-concat embed format
Three follow-ups to PR #1909, all in `pkg/codegen/templates/inline.tmpl`
(plus the regenerated `*.gen.go` files and migrated callers):
1. Revert the embedded spec back to `var swaggerSpec = []string{...}`.
PR #1909 replaced the historical slice-of-chunks form with a single
`const swaggerSpec = "" + "chunk" + "chunk" + ...`. With thousands of
80-char chunks (large APIs produce them) the Go compiler folds the
chained `+` at compile time, and that fold is materially slower than
parsing a slice literal. `decodeSpec` now joins the slice via
`strings.Join` before base64-decoding; flate compression, base64
encoding, the 80-char chunk size, the lazy `decodeSpecCached` /
`rawSpec` pipeline, and `PathToRawSpec` all stay exactly as PR #1909
landed them.
2. Add `GetSpec() (*openapi3.T, error)` as the canonical accessor, and
demote `GetSwagger()` to a `// Deprecated:` thin wrapper.
The kin-openapi spec type was renamed from `openapi3.Swagger` to
`openapi3.T` years ago; `GetSwagger`'s name is a stale relic. `GetSpec`
carries the body that `GetSwagger` had, and `GetSwagger` becomes a
one-line `return GetSpec()` retained for backwards compatibility.
External callers still upgrading to a newer version of oapi-codegen
will see the `// Deprecated:` hint surfaced by gopls/godoc; in-tree
callers across `examples/` and `internal/test/` are migrated to
`GetSpec()` because the repo's lint rule rejects calls into deprecated
functions and would otherwise block CI.
3. Add `GetSpecJSON() ([]byte, error)` returning the embedded JSON.
Decompressed, base64-decoded, but not unmarshaled into `*openapi3.T`.
A one-line wrapper around the existing `rawSpec()` cache, so repeated
calls don't re-decompress. This fills a long-standing gap: callers who
want to operate on the raw OpenAPI document (re-marshal to YAML, hand
to a different parser, run an overlay, dump to disk) previously had to
either invoke `openapi3.T.MarshalJSON` after `GetSpec` or hand-roll
base64+flate decode.
Migrated callers (mechanical; no logic changes):
- 7 user-side example files under `examples/` (petstore variants for
each framework, authenticated-api echo + stdhttp).
- 12 test files under `examples/petstore-expanded/*/petstore_test.go`,
`internal/test/externalref/imports_test.go`,
`internal/test/issues/issue1825/overlay_test.go`,
`internal/test/compatibility/preserve-original-operation-id-casing-in-embedded-spec/spec_test.go`.
New test:
- `examples/petstore-expanded/chi/petstore_test.go::TestSpecAccess`
covers `GetSpec` and `GetSpecJSON` end-to-end (asserts the bytes are
valid JSON and the parsed spec has a non-empty `OpenAPI` version
field). `GetSwagger` is intentionally not exercised — its body is
`return GetSpec()` and the lint rule blocks an in-tree call. If we
later want regression coverage for the wrapper specifically, one
test annotated with `//nolint:staticcheck // SA1019` would do it.
Verification:
- `make generate` is idempotent; spot-checking
`examples/petstore-expanded/chi/api/petstore.gen.go` confirms the
slice form, the three new accessors, and the `// Deprecated:` marker
on `GetSwagger`.
- `make test` passes (exit 0) across the root module and all eight
child modules.
- `make lint` reports `0 issues.` across the same nine modules — no
remaining in-tree calls into the deprecated wrapper.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Marcin Romaszewicz <marcinr@gmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>