Doc site update#43
Merged
Merged
Conversation
Combed all commits since master, mapped each to its go-swagger issue and
the tracker's "Need doc" flag, and verified the doc-site against the
fixture/golden each commit locked in.
Prose corrections (reference + tutorials):
- fix a factually-wrong notice claiming a deprecated model field emits no
x-deprecated (it now does, incl. via the godoc `Deprecated:` synonym);
- drop `array` from the swagger:type accepted-values list (code rejects it);
- document SkipEnumDescriptions and fix the misleading swagger:enum sample
that hid the description folding;
- document +kubebuilder/+marker and Go-directive stripping from prose;
- interface{}/[]any any-schema, plain-identifier names, allOf-in-response
$ref, json-vs-form param naming, map-field skip, grouped type decls,
referenced-primitive enum, ScanModels reachability, function-body routes,
strfmt array items, generics/external embedding.
New-feature example panes (test-backed regions + goldens):
- object validations (minProperties/maxProperties/patternProperties);
- field-level swagger:type override;
- externalDocs on meta, operation and full schema (block + inline forms);
- x-deprecated via the godoc `Deprecated:` convention;
- examples on responses and on $ref'd defined-type fields (allOf override arm).
docs/examples go.mod tidied (spec v0.22.6, required by the current root).
go test ./docs/examples/... green, golangci-lint --new-from-rev master clean,
Hugo build 52 pages 0 warn/err.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
…lDocs, examples) Second alignment pass over the commits added to fix/backlog-lot1 since the first pass (range 58130ef..0dd122b). Branch rebased onto the advanced fix/backlog-lot1 first (example tests stayed green — no golden drift). New feature exemplified — swagger Tags (go-swagger#2655, closes #1121): - meta `Tags:` block (name/description/nested externalDocs/x-* per tag) → the spec's top-level `tags`; added a Tags region to the meta example, a `## Tags` tutorial section, a `tags` keyword reference entry + summary row, and the keyword to the swagger:meta and swagger:route/operation legal-keyword lists (route/operation body `tags:` list, unioned with the header-line tags). externalDocs completion (go-swagger#2655): - field-level and $ref'd-field (allOf-lift) externalDocs exemplified by extending the routes externaldocs region; prose in routes-and-operations and keywords; fixed the now-false "tags do not yet carry externalDocs" line. Structured examples (go-swagger#1542/#1268): - a JSON object/array literal example is parsed into a structured example (a bare comma list stays a string); new complexexample region + pane + notice. Prose corrections: model title/description heuristic (#1118), time.Time -> date-time (#1078), field-level swagger:strfmt int64 override + uint formats (#1512), inline Parameters block on swagger:route (#1279), embedded-field annotation propagation + unsupported-type warn-and-continue (#2701, #1133/#1174), and the swagger:route Responses line-based-sub-language description caveat (#989). go test ./docs/examples/... green, golangci-lint --new-from-rev master clean, Hugo build 52 pages 0 warn/err. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
Two annotation-driven shaping techniques had reference-only coverage and no
worked, test-backed example. Added as Shaping how-to pages, each backed by a
golden-verified example package under docs/examples/shaping.
Inline response bodies (shaping/inlineresponses):
- the body: responses sub-language (body:string, body:[]Pet, body:Pet, with
trailing words becoming the response description) declares a route's
responses without a swagger:response struct. Golden is the GET /pets path
item.
Forcing a conformant format (shaping/formats):
- a field-level swagger:strfmt int64 overrides the Go-derived vendor uint64
format ({integer, uint64}) with a precision-safe, JSON-conformant
{string, int64}. Golden contrasts a default and an overridden field.
go test ./docs/examples/... green, golangci-lint --new-from-rev master clean,
Hugo build 54 pages 0 warn/err.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
The Swagger 2.0 polymorphism use case had only a terse discriminator keyword entry and no worked tutorial. Added tutorials/polymorphic-models.md backed by a new test-covered concepts/polymorphism package. - base Pet declares `discriminator: true` (+ required) on a field, so the schema carries `discriminator: "petType"`; subtypes Cat/Dog compose via swagger:allOf (allOf: [$ref Pet, inline own fields]). Goldens for the base and both subtypes. - documents the verified constraints: the discriminator property must be required, and the discriminator value for each subtype is its definition name — swagger:discriminatorValue (custom values) is not implemented in the scanner. Enriched the discriminator keyword entry and cross-linked from the model-definitions swagger:allOf section. go test ./docs/examples/... green, golangci-lint --new-from-rev master clean, Hugo build 55 pages 0 warn/err. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
…itions A field whose type resolves to a named model is a $ref, and a bare $ref cannot carry sibling keywords (JSON Schema draft 4). codescan wraps the $ref as a member of an allOf so a description, vendor extension, or value override is not lost. This behaviour was scattered (DescWithRef, defined-type example/default, externalDocs lift) and is now consolidated. - new "Decorating a $ref" subsection in model-definitions.md, backed by the test-covered concepts/refoverride package. Verified landing spots: description and x-* extensions stay on the property; default/example ride a second allOf member; required rides the parent. Golden shows a $ref field keeping its description and x-ui-order via a single-arm allOf wrapper. - cross-linked to descriptions-beside-a-ref (DescWithRef, the description-only case) and examples-and-defaults (value overrides on a $ref'd field). go test ./docs/examples/... green, golangci-lint --new-from-rev master clean, Hugo build 55 pages 0 warn/err. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
…ers x-*, more) Third alignment pass over the commits added to fix/backlog-lot1 since the last pass (range 0dd122b..b4ce007). Branch rebased onto the advanced fix/backlog-lot1 first (example tests stayed green — no golden drift). New capability exemplified — author x-* on parameters and headers (go-swagger#1609): - an Extensions: block works on schema fields, parameters, and response headers alike (and author-supplied x-* survive SkipExtensions). New paramext region in shaping/extensions + an "Authoring x-* on parameters and headers" section in vendor-extensions.md; extensions keyword scope updated. Prose corrections: - swagger:parameters/response structs bind across all scanned packages by operation id (#1742); - an anonymously embedded `in: body` struct is the body ($ref), not promoted headers (#1635); - a multi-name field group emits one property per name, json rename can't apply (#2638); - simple-schema array elements can't be a $ref: named primitive expands inline, object element dissolves to items:{} with a warning (#1088); - per-media-type response examples via the swagger:operation YAML body (#1713); - Version: is static — set doc.Info.Version after Run or overlay via InputSpec (#1725); - same-name cross-package definition collisions are silently merged; use swagger:model <DistinctName> (#1734). go test ./docs/examples/... green, golangci-lint --new-from-rev master clean, Hugo build 55 pages 0 warn/err. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
…OST body) Fourth alignment pass over the commits added to fix/backlog-lot1 since the last pass (range b4ce007..270d4b4). Branch rebased onto the advanced fix/backlog-lot1 first (example tests stayed green — no golden drift). New exemplified — declaring security (go-swagger#1795): - basic/apiKey auth was documented only in the keyword reference. Added a SecurityDefinitions: + Security: block to the meta example (basic_auth + api_key, with a global basic_auth requirement) and a "## Security" section to document-metadata.md; the meta pane now shows securityDefinitions + security. New exemplified — POST request body (go-swagger#1772): - no in: body *request* parameter example existed (only response bodies). Added a bodyparam region to concepts/routes (CreatePetParams.Body -> request body $ref) on POST /pets/import + a pane in routes-and-operations.md. Prose: - one struct may carry several swagger:parameters lines whose operation-id lists accumulate, so a long list can be split across lines (go-swagger#1865). Already covered (no change): block-comment routes (#1595), PATCH (#1867), 204 description (#1852), inline response description (#1828), file type (#1887), grouped decls / func-body routes (#1891), usage/host/overlay questions. go test ./docs/examples/... green, golangci-lint --new-from-rev master clean, Hugo build 55 pages 0 warn/err. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
…llets, more) Fifth alignment pass over the commits added to fix/backlog-lot1 since the last pass (range 270d4b4..40d8af1). Branch rebased onto the advanced fix/backlog-lot1 first (tests green). Prose-only — no example packages touched. - markdown-style bullets (`* item`, `+ item`) are recognised like the dash form and normalised to `- ` (matching gofmt), across prose descriptions, flex-lists, and enum bodies (go-swagger#1726): updated sub-languages.md; - a swagger:model / swagger:parameters on a type local to a function body is discovered (go-swagger#1934): broadened the func-body note; - the cross-package "Across packages" note now covers swagger:operation, not just swagger:route (go-swagger#1955); - the Polymorphic models tutorial gains a subtype-reachability note — subtypes need ScanModels or a reference; codescan does not auto-discover them from the base (go-swagger#1913). Already covered: ./... subpackage scanning (#1931, scoping-the-scan). Out of scope: property order (#1960). Hugo build 55 pages 0 warn/err. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
The brief Security note in document-metadata wasn't enough to articulate the security workflow. Added tutorials/security.md backed by a new test-covered concepts/security package, covering three paths (behaviour probed first): - Declare the schemes: swagger:meta SecurityDefinitions (apiKey + oauth2 with scopes) plus a Security: document-wide default requirement. - Require a scheme on a route: a route's Security: override (oauth2 read,write); a route with no Security: inherits the document default. - Keep security out of app code: the gateway/mesh case — scan app code that has NO security annotations and overlay the schemes + requirement via Options.InputSpec, so the merged spec is secured from the base. Trimmed the document-metadata Security note to a pointer to the new tutorial. go test ./docs/examples/... green, golangci-lint --new-from-rev master clean, Hugo build 56 pages 0 warn/err. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
Sixth alignment pass. Rebased onto fix/backlog-lot1 (git auto-merged my edits with a fixer's swagger:alias rewrite). The fix/quirks-F-series branch landed, fixing behaviours the doc-site previously documented as limitations; no example golden drifted, so this is a prose reconciliation. - swagger:type (F3) is now a uniform inline directive: it never emits a $ref; integer/number/boolean resolve; []T inlines recursively; new `inline` value; `array` is deprecated (→ inline + warning); `file` is rejected; an unknown token inlines the Go type (or a known type name) with a diagnostic; with swagger:strfmt the type wins and the format is kept only if compatible. Rewrote the annotations.md and model-definitions.md sections (which said "array/file not accepted; unknown ignored" — no longer true). - swagger:name (F5) now works on struct fields, not just interface methods; updated the model-definitions tutorial framing (the reference was already correct). - swagger:alias (F8) is deprecated (a fixer rewrote the reference). Reconciled the dangling cross-references: the annotation-index row (was "$ref to target") and the alias-rendering how-to, and fixed the heading anchor (#swaggeralias--deprecated). - readOnly: noted it as the answer to "hide composition for create vs read" (#1992) — server-set fields are readOnly, or use distinct request/response models. go test ./docs/examples/... green (no golden drift), Hugo build 56 pages 0 warn/err. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
Seventh alignment pass (range d57ac9f..664a347, rebased onto fix/backlog-lot1). The two new commits are a tracker-only docs commit (#2027 embedded structs — already covered by type-discovery; #2053 scan-dir — CLI/out-of-scope) and a test-lock commit that locks behaviours the doc-site already exemplifies (operation security #2062, body-param example #2064, field extensions #2106, SkipExtensions #2119) — confirming the recent examples are correct. Only addition: a one-line note in the Security tutorial that a swagger:operation YAML body can also carry a `security:` requirement (the schemes themselves stay global swagger:meta — OAS2 has no per-operation securityDefinitions), closing the swagger:route-vs-operation gap for #2062. Hugo build 56 pages 0 warn/err. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
A full sweep of the 78 "Need doc" rows in the split-out backlog-triaged-ledger.md found every actionable item already covered or out of scope, except two: - #1026 (x-logo): infoExtensions was documented in the keyword reference but never shown. Added an InfoExtensions: block with x-logo to the concepts/meta example (lands in info.extensions, rendered by ReDoc / Swagger UI) and a note in document-metadata. - #3134 (multiple API versions): added a note to scoping-the-scan that you run a separate scan per package tree (./v1/..., ./v2/...) for separate specs. The remaining ledger 📖 rows are covered (title/description heuristic, POST body param, reachability, the doc-site itself) or out of scope (CLI/environmental flags, x-go-type which is a generate-side extension, wont-fix dynamic examples). go test ./docs/examples/... green, golangci-lint --new-from-rev master clean, Hugo build 56 pages 0 warn/err. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
…ken footgun Eighth alignment pass (rebased onto fix/backlog-lot1 incl. #2547). More F-series quirk fixes landed; reconciled the docs (all probed) and fixed one self-inflicted example bug. - swagger:strfmt / swagger:type + swagger:model now publish a first-class definition that fields $ref (F1/F2), instead of an orphan inline. Updated the annotations reference (strfmt, type) and the model-definitions tutorial. - swagger:enum + swagger:model likewise yields a definition + $ref, and a bare swagger:enum on the type declaration is accepted (F4). The reference was updated by the fixer; updated the tutorial to match. - a json-tagged embedded struct now nests as a $ref property instead of promoting its fields (go-swagger#2038) — type-discovery note. - a string example:/default: with surrounding double quotes has them stripped (example: "" sets an empty string) (go-swagger#2547). Edge case: any comment line that begins with a swagger:<name> token is parsed as that annotation, even in prose. Added a warning to "How annotations attach". This footgun collapsed the shaping/formats example once F1 made a type-level swagger:strfmt effective (a prose line started with "swagger:strfmt int64"); reworded the example so no line starts with the token. go test ./docs/examples/... green, golangci-lint --new-from-rev master clean, Hugo build 56 pages 0 warn/err. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
Ninth alignment pass (rebased onto fix/backlog-lot1; range 64ceb83..f10eab7). The two new commits are a tracker dedup (#2412 = the covered #1887 file param) and a test-lock (#2407 array example, #2409 type-level extensions, #2419 field type-override, #2441 binary body) — no golden drift, no fixer doc-site changes. Only update: the "Authoring x-*" note said extensions work on schema fields, parameters and headers; broadened it to include a model itself (the x-* lands on the definition), closing #2409's "annotate structures with extensions" intent. (The issue's literal x-go-type ask is a generate-side extension, out of scope.) File upload (#2441/#2412) is covered by swagger:file; #2419 by swagger:type; #2407 by the array-example docs. Hugo build 56 pages 0 warn/err. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
Tenth alignment pass (rebased onto fix/backlog-lot1; range f10eab7..335cb4c). The three new commits are a style cleanup, a tracker cross-reference, and a test-lock — no golden drift, no fixer doc-site changes. - #2384 (verbatim pattern escapes): the `pattern` keyword reference already said "preserved verbatim", but the reported confusion was specifically about backslash escapes (`\n`, `\d`) being interpreted. Spelled that out — they reach the spec as literal two-character sequences, not interpreted by the scanner. Verified covered/out of scope: #2371 (array response = #1881), #2379 (cross-package $ref), #2383 (func-local structs = #1934), #2353 (body+path params), #2398 (duplicate-definition warning — wont-fix; the silent-merge behaviour + swagger:model workaround is already documented as the #1734 same-name-collision note). Hugo build 56 pages 0 warn/err. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
A global/route Security: requirement written as a YAML sequence (`- auth0: []`) previously mis-parsed (keyed by the literal "- auth0"); it now parses identically to the flat `auth0: []` form. Noted both forms in the Security tutorial. The concepts/security example uses the flat form — no golden drift. Hugo build 56 pages 0 warn/err. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
Prepares a Shaping-the-output section for the upcoming feat/name-identity-cyclic-ref feature (#2637, #2783): conflict detection and auto-resolution of $ref definition names, with author control over the exposed names. The page is a draft (draft: true, excluded from the live build) holding a brief outline of what it will cover — when names collide, what auto-resolution guarantees, how the author keeps exposed names under control, and when to tune vs let it resolve. Flip draft:false and add test-backed example panes once the feature lands on the base branch. It is the author-facing counterpart to the existing Same-name collisions note in the Model definitions tutorial. Hugo build 56 pages 0 warn/err (draft excluded); renders cleanly with --buildDrafts. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
…agger:ignore (#2311) Rebased onto fix/backlog-lot1. The landed fix #2479 makes an empty `Security: []` emit an explicit empty requirement — a route's public opt-out, distinct from omitting the keyword (which inherits the document default). This is the case the Security tutorial had to omit originally because it didn't work yet. - added a publicReport route (Security: []) to the concepts/security example (golden public.json = security: []) and a pane/note in the Security tutorial. - #2311: documented that swagger:ignore also drops a single struct field (the reference already covered it; added the missing note to the tutorial). go test ./docs/examples/... green, golangci-lint --new-from-rev master clean, Hugo build 56 pages 0 warn/err. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
…ame: keyword Rebased onto fix/backlog-lot1. Three landed changes (all probed): - #2294: the Security: block is now parsed as real YAML, not a bespoke line scanner. Reinspected the Security tutorial end to end — rewrote the syntax prose (a YAML sequence of requirement objects; multiple keys in one item are ANDed, separate items ORed; flow/block scopes; Security: [] opt-out; legacy bare mapping still read OR-per-key). Converted the concepts/security example to the idiomatic sequence form and added an AND route (archiveReport requires both api_key and oauth2). Rewrote the keywords.md security entry. - #2396: a bracketed enum form `enum: [a, b, c]` now strips the surrounding brackets (equivalent to the unbracketed comma list). keywords.md enum. - name: keyword: a field-doc keyword that sets the swagger:parameters parameter name and the swagger:response header key (the field-doc equivalent of swagger:name, stripped from the description). New keywords.md entry + notes in the swagger:parameters / swagger:response references. go test ./docs/examples/... green, golangci-lint --new-from-rev master clean, Hugo build 56 pages 0 warn/err. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
…quivalent) A documentation-vantage review (fixers paused) probed several behaviours and found the name:/swagger:name relationship I described last pass is inaccurate: they have disjoint scopes. The `name:` keyword works on swagger:parameters and swagger:response header fields but is ignored on a swagger:model property; `swagger:name` works on model properties / interface methods but is not consulted on a parameter field. Reworded keywords.md `### name` and the annotations.md swagger:parameters note to state the split explicitly rather than calling them equivalent. (Two further consistency smells found in the same review — body:<Type> response description defaulting to the type name, and a JSON-literal example/default on a $ref'd field staying a raw string — are recorded as G1–G3 in .claude/plans/doc-site-quirks.md for the fixers; no doc-site change needed.) Hugo build 56 pages 0 warn/err. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
…sponse-bodies
The G1 fix (derive a body: response description instead of echoing the type name)
is merged, so the inline-response-bodies how-to no longer needs to work around it
by always adding trailing description text. Dropped the trailing words on two of
the example's responses to demonstrate the derivation: `400: body:string` now
shows the HTTP status reason ("Bad Request"), and `default: body:Pet` shows the
Pet model's godoc — while `200` keeps an explicit description to still show the
trailing-words form. Golden + prose updated.
go test ./docs/examples/... green, Hugo build clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
…agger#2596)
go-swagger#2596 asks for swaggo-style per-route payload overrides
(body:APIResponse{Data: StatusReport}) on a generic response envelope whose
Data field is interface{}. codescan won't add a syntax that invents an
undeclared type, and the triager marked it wont-fix.
There is a supported pattern, though: a doc-only struct that embeds the generic
envelope and shadows the open payload field with a concrete type. The shadowing
field wins both in codescan and in encoding/json, so the spec gets a concrete
$ref while the handler keeps returning the generic envelope (and the doc struct
remains a valid, identically-marshaling type).
New 'Documenting generic responses' shaping how-to, backed by a golden-verified
example package (shaping/genericenvelopes): the opaque baseline, the
embed-and-shadow fix, a before/after compare, and two routes specialising the
same envelope to different payloads.
* contributes go-swagger/go-swagger#2596
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
The G2 fix (fix/quirks-g2-name-scopes) makes name: the one canonical
field-naming keyword, honoured uniformly on model properties, interface methods,
parameters, and response headers; swagger:name is retained as the legacy form.
Align the docs to match:
- keywords.md ### name: rescope to 'any field', state the precedence
(name: > swagger:name > json tag > Go field name), note the new
context-invalid diagnostic when swagger:name is used on a param/header.
- annotations.md swagger:parameters note + swagger:name section: drop the
'disjoint scopes' caveat; frame swagger:name as legacy, name: as canonical.
- model-definitions.md swagger:name section: same reframe + a new test-backed
pane showing name: renaming a tag-less model field and winning over a
co-located swagger:name and json tag.
New golden witness concepts/models Account (namekeyword region): proves the
keyword renames a model property and the most-explicit-wins precedence.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
…e examples (quirk G3, #2871) The G3 fix (fix/quirks-g3-ref-example-coercion) coerces a JSON object/array literal example:/default: into a structured value on a $ref'd field's allOf override arm, instead of carrying it as a raw escaped string (a bare scalar still stays a string, since the referenced type is unknown on that arm). examples-and-defaults.md 'On a defined-type field': add a test-backed pane (concepts/examples Place, refstructured region) showing a JSON-object example landing as real JSON on the override arm, and spell out the scalar exception. Also documents the re-triaged #2871: because a per-media-type example lives on the operation's response, one shared model can carry a different example per response code and per operation — no struct-per-case needed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
…#2592) Re-triage 4aed77f locks #2592: a response body can be composed from two models by embedding them with swagger:allOf, yielding allOf:[{$ref:A},{$ref:B}] — a way to wrap a response with an added payload (e.g. an auth token) without an open Data field. Add a 'Composing a body from several models' section to the generic-responses how-to, backed by a new golden witness (shaping/genericenvelopes LoginResult, compose region) that composes UserSummary + AuthToken. Complements the embed-and-shadow technique on the same page: shadow to specialise one open field, allOf to union several models. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
The #1499 fix makes a field-level swagger:type apply on swagger:parameters
fields, not just schema fields: a struct-typed parameter field that would
otherwise come out typeless (invalid Swagger 2.0) is collapsed to a simple
parameter. The argument is restricted to a scalar or a []-wrapped scalar there
(inline / type-name forms are rejected — a non-body parameter has no schema to
inline into).
- annotations.md swagger:type: add 'swagger:parameters field doc' to where it
goes, with a note on the parameter-scope argument restriction and the
strfmt-rides-as-format interaction.
- routes-and-operations.md swagger:parameters: a new test-backed pane showing
a struct-typed field collapsed to a string param and a []-form to an
array-of-string param.
New golden witness concepts/routes filterPets (paramtype region): proves the
override yields type:string and type:array/items:string on parameter fields.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
Documents the additionalProperties / patternProperties feature set that landed on
the backlog branch (go-swagger#2251, #2539, #3005):
- Go maps render as objects (additionalProperties from the element type);
- which map keys survive (#2251): string, integer/unsigned kinds, and
TextMarshaler — others warn-drop;
- swagger:additionalProperties marker (true / false / typed / model ) for
open / closed / typed objects;
- the additionalProperties: field keyword (map override; 'd field rides an
allOf sibling);
- the typed swagger:patternProperties marker (regex -> typed value), with the
beyond-Swagger-2.0 (JSON-Schema draft-4) caveat;
- the object-only / lowest-priority / no-SimpleSchema precedence rules.
New golden-backed example package concepts/maps covers every form (natural map,
integer key, closed/open/typed/ref markers, field keyword incl. allOf-on-$ref,
typed patternProperties). Placed at tutorial weight 13, after model-definitions.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
Adds the two new object-shape annotations + the field keyword to the reference
surface, matching the 'Maps & free-form objects' tutorial:
- annotations.md: swagger:additionalProperties and swagger:patternProperties
sections (arg grammar, precedence, beyond-OAS2 note), index + quick-ref table
rows;
- keywords.md: new additionalProperties field-keyword section + table row +
TOC; cross-link the typed marker from the patternProperties section;
- grammar.md: ANN_ADDITIONAL_PROPERTIES / ANN_PATTERN_PROPERTIES tokens;
- annotation-index: rows for both markers;
- validations.md: pointer to the new tutorial from the object-validation note.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
The feat/name-identity-cyclic-ref work has merged into fix/backlog-lot1,
so the drafted Shaping page can come out of draft and be backed by a real
witness instead of a scaffold.
New witness docs/examples/shaping/nameconflicts/ scans a small package
tree that exercises every path the reduce stage takes:
- billing.Account vs identity.Account -> BillingAccount / IdentityAccount
(cross-package collision, qualified by package segment, deterministic);
- ledger.Entry declared twice in one package -> one keeps "Entry", the
other reverts to its Go name "Reversal" (same-package duplicate);
- Bag's `swagger:additionalProperties Widget` -> $ref to catalog.Widget
(cross-package type-name keyword resolving a unique bare leaf, d8f654c).
The test asserts the resolved definition keys and refs and writes three
goldens the page renders, so the prose can never drift from real output.
Page rewrite covers: how identity-keyed deconfliction works, the
x-go-package provenance extension, the same-package fallback, the
cross-package leaf rule for swagger:type/additionalProperties/
patternProperties, name pinning via swagger:model, and the NameConcatBudget
/ EmitHierarchicalNames tuning surface (with the nested-pointer caveat).
Reconcile two now-stale spots: the model-definitions "Same-name
collisions" notice (was "silently merged ... until auto-disambiguation
lands") and a cross-package leaf note in the maps tutorial.
* contributes go-swagger/go-swagger#2637
* contributes go-swagger/go-swagger#2783
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
Two opt-in, default-off Options landed on fix/backlog-lot1; both are now covered by test-backed panes. EmitXGoType (#2924) stamps an x-go-type vendor extension carrying the fully-qualified originating Go type on every definition, beside x-go-name / x-go-package, for round-tripping a spec back to its source types. Extended the shaping/extensions witness with an EmitXGoType scan + xgotype golden (asserts the stamp is the FQ type and that it still yields to the SkipExtensions umbrella). Documented as a new "Stamping x-go-type" section in the vendor-extensions how-to (off -> on compare). SingleLineCommentAsDescription (#2626) routes any single-line doc comment to description instead of title / summary; multi-line comments keep the existing split. New witness shaping/singleline pairs a model and a route, scanned both ways, asserting the comment moves from title/summary to description uniformly. New shaping page "Single-line comments as descriptions" with the off/on compare. Also added both knobs to the Options table in the library-usage page. * contributes go-swagger/go-swagger#2924 * contributes go-swagger/go-swagger#2626 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
usage/ is the original scaffold (go-openapi#37), superseded by the top-level getting-started/ tutorials/ shaping-the-output/ maintainers/ sections. Its getting-started/usage-as-a-library.md duplicated the maintained getting-started/usage-as-a-library.md but had drifted behind (missing the SkipEnumDescriptions row, stale relative links). Every cross-site relref already points at /getting-started/usage-as-a-library, and the page itself linked back out to the top-level tree. Remove the duplicate page and its now-childless section index, and repoint the one inbound link (project/README.md) at the maintained section. The usage/_index.md uses {{< children >}} so it needs no edit. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #43 +/- ##
=======================================
Coverage 81.83% 81.83%
=======================================
Files 80 80
Lines 7433 7433
=======================================
Hits 6083 6083
Misses 1006 1006
Partials 344 344 ☔ View full report in Codecov by Harness. |
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
1 participant
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.
Change type
📃 Documentation update
Short description
Fixes
Full description
Checklist