docs: migrate takes -s|--specification and finds the solution
The solution (.sln/.slnx) is optional: the nearest folder with one above the specification, then above the current directory. The old -s <solution> -p <spec> spelling still works.
e537401
docs: narrow ATC_API_OPR022 to 403 responses on anonymous operations
110e98f
docs: document bearer-only security and how authentication scheme names are mapped
e643b7e
docs: scope OPR008/OPR009 to read operations and give them rule sections
The cardinality rules enforce a read-side naming convention, but they were
documented as applying to every operation. They now run on GET and QUERY
only, so the rule table, the extension table and the worked example say so,
and a new note explains why a bulk action like resendPendingDevices is
correctly named rather than a defect.
The rename-first advice was written for aggregate reads and produced bad
names when followed for bulk actions, so it is split in two: rename an
ambiguous read, and leave a bulk action alone.
Analyzer-Rules.md also gains ATC_API_OPR008 and ATC_API_OPR009 sections.
Constants.Documentation.GetRuleUrl builds an anchor from the rule id, which
resolves only against a heading of exactly that text, and the page had
headings for the CLT and VER rules only. Without them the new help links on
these two diagnostics would land on the top of the page.
734a074
docs: explain the nullability spellings, and document the VER rules
Two new pages and the reference entries behind them.
Working with Nullability answers the question people actually ask when
their models change - who decided this, and why. The OpenAPI Initiative
removed `nullable` in February 2021; parsers honoured it for four more
years; a 2025 release stopped. It carries the old and new spellings side
by side, the rule that `nullable` only applies beside a `type`, and a
support matrix for what this generator accepts at each version.
Upgrading to v2 is the consumer-facing version: am I affected, how do I
tell, what do I write instead. It moves here from `docs/` in the code
repository, where a second copy would only drift.
Analyzer Rules gains the VER category and a section per rule, each with
the offending YAML and its rewrite. The rule headings are now bare ids so
the help links in the diagnostics resolve to them - the CLT headings are
trimmed for the same reason.
5b41b2d
docs: mark the SWR/MSW snapshot coverage gap as fixed
TS-Hooks-Swr and TS-Mocks-Msw are now master folders in ScenarioDiscovery, so
both extractors' output is snapshotted. That gap was the root cause of two
defects shipping unnoticed.
14ab705
docs: document the QUERY shape rules and webhook verb handling
Analyzer-Rules gains ATC_API_OPR028 and ATC_API_OPR029 - a QUERY with no
requestBody is a GET with a less widely understood verb, and a QUERY declaring
201/409 contradicts the safe/idempotent contract that lets callers and caches
retry it freely.
Working-with-OpenAPI now summarises all three build-time rules in one table,
notes that webhooks honour the declared verb, and records that streaming over
QUERY is buffered rather than streamed. Working-with-Webhooks shows the
MapMethods form for a non-standard verb.
Roadmap marks the webhook fix and the two new rules as shipped, and records the
two deliberately declined items - streaming over QUERY and an
X-HTTP-Method-Override fallback - so the reasoning is not rediscovered later.
76970a9
docs: document ATC_API_OPR027 and the runnable Showcase QUERY example
Analyzer-Rules gains ATC_API_OPR027, including why the rule stays quiet on a
bounded array whose item length cannot be derived - guessing there would fire on
specs that are perfectly fine - and why it applies to GET only.
Working-with-OpenAPI points at sample/Showcase as a worked example that can
actually be run, with the recorded 414-vs-200 comparison for the same 1000 ids,
and notes that the build now warns before you hit the 414 at all.
1108803
docs: add ATC_API_CACHE001 and warn that QUERY is dropped from the runtime OpenAPI document
Analyzer-Rules gains a Caching (CACHE) category and ATC_API_CACHE001, explaining
why output caching on a non-GET/HEAD verb caches nothing, why opting QUERY in is
still not enough (the middleware keys on the URL, not the body), and how
inheritance and x-cache-enabled: false interact with the rule.
Working-with-OpenAPI gains a prominent warning that Microsoft.AspNetCore.OpenApi
publishes at OpenAPI 3.1.1 and silently drops a QUERY endpoint from the document
served at /openapi - while still emitting its now-orphaned request schema, which
makes the omission easy to skim past. An API using QUERY must publish its source
YAML as the contract.
Working-with-Caching now cites the Microsoft Learn rule directly and points QUERY
operations at HybridCache. Roadmap records the fixed, cannot-fix and still-open
gaps separately.
9498303
docs: document OpenAPI 3.2 HTTP QUERY support and the current limitations
Adds an 'HTTP QUERY and Custom Verbs' section to Working-with-OpenAPI with the
motivating case - fetching 1000 records by id, where a GET is ~40 KB of request
line against Kestrel's 8 KB default and fails with 414 - plus the YAML, the
generated server/client/TypeScript output, and what is still rough.
Roadmap gains a 3.2 row in the version table, a 3.2 feature matrix and a
known-gaps table with status. Working-with-TypeScript-Client documents that a
query: operation now yields useQuery/useSWR with the body in the cache key and
that non-standard verbs use an http.all MSW handler. Working-with-Caching warns
that output caching serves GET/HEAD only, so x-cache-* on a QUERY endpoint
caches nothing.
README and Home gain a Key Features row and 3.2.x in the supported versions.
247b919
docs: sync wiki with the client-testability branch
Covers the parts of the branch that were not already documented, checked
against the generator source rather than the commit messages.
Generated endpoint results are now partial. `{Operation}EndpointResult`
is emitted as `partial class` rather than `sealed`, unconditionally and
with no marker-file flag. That is easy to confuse with
`generatePartialModels`, which is opt-in and applies to models only, so
every mention says so explicitly. Documented in API-Reference as part of
a new Client Types table, in Working-with-CSharp-Client-Testing as a way
to keep repeated test assertions next to the result, in
Working-with-How-To-Guides next to the existing partial-model guidance,
and in Migration-Guide as a no-action-required change. The typed client
class stays sealed; each page points at `I{ClientName}` instead.
ATC_API_SCH021 can break a build. The rule itself was already listed in
Analyzer-Rules, but nothing said that a project consuming a third-party
spec that declares `ProblemDetails` and building with
TreatWarningsAsErrors will now fail. Marker-Files documents the override
and the NoWarn escape hatch under Error Response Formats;
Migration-Guide gives it a subsection and drops the "purely additive"
framing that is no longer true. The old advice to fully qualify
`ProblemDetails` at the call site is removed - the shadowed second type
is no longer emitted, so the ambiguity it worked around cannot arise.
Polymorphic base placement. Working-with-OpenAPI already described
oneOf/anyOf as supported, which the branch makes true rather than
changes; the one genuinely new user-visible detail is that the base and
its converter land in its variants' Models namespace, and that a variant
outside that set gets a using. Added as a sibling of the three strategy
subsections since it applies to all of them.
Development-Notes had the most staleness. The snapshot section described
a workflow that no longer exists. It now covers the four master folders
and the fact that each holds its own marker file, hint-name file naming
flat in the folder, the three guard tests including
Snapshots_HaveNoOrphans, and the compilation gate with its shrink-only
ratchet - plus a step in "Adding a New Scenario" saying a new scenario
is expected to compile. Also corrected: ServerDomain is in the
compilation gate (its ratchet rows are derivative of their Server row),
PolymorphicTypeEmitter now lives in SourceGenerator alongside
RoslynSchemaExtractor, the sample folders are not nested under Minimal,
and Atc.Rest.Api.Client.Testing and the two ThirdParty sample folders
were missing. The hard-coded per-project test counts are dropped rather
than re-derived; they were wrong and would go stale again.
576e7f3
docs: document typedClientResultStyle and ATC_API_SCH021
- Analyzer-Rules: add ATC_API_SCH021 (spec-defined ProblemDetails ignored in
EndpointPerOperation mode in favour of the built-in type).
- Working-with-CSharp-Client-Testing: replace the obsolete "fully qualify
ProblemDetails to avoid an ambiguous reference" caveat. The duplicate type is
no longer generated, so there is only ever one ProblemDetails in scope and no
qualification is needed.
- Marker-Files / Working-with-CSharp-Client: document the typedClientResultStyle
Throw|Result option (carried over from the earlier 2.4 work).
982d2be
docs: document the Atc.Rest.Api.Client.Testing package in the client testing page
edaa519
docs: add C# client testing page and document generated interfaces and result factories
a6a22d4
docs: document streaming and paginated response consumption
Add "Consuming Streaming Responses" and "Consuming Paginated Responses"
sections to Working-with-CSharp-Client, under the TypedClient wiring
section.
The OpenAPI page already documents the `x-return-async-enumerable` and
pagination `allOf` schema shapes on the server/spec side, but the client
consumption side - how to `await foreach` a streaming operation and how to
page through a `PaginatedResult<T>` using `Continuation`/`PageIndex` - was
undocumented. Both patterns are already demonstrated end to end by the
Showcase sample's `/accounts/paginated` and `/accounts/async-enumerable`
endpoints, which the new sections link to.
5958395
docs: document client granularity, client naming and namespace resolution
Cover the typed client improvements from the
`feature/typed-client-improvements` branch.
Marker-Files:
* Add `clientGranularity` and `clientName` to the options table.
* Add a "Client Granularity" section contrasting `PerArea` (default) with
`Single`, including the flattened namespace layout the latter produces.
* Add a "Namespace Resolution" section describing the three-rule chain
(marker `namespace`, then `info.title` when it is already a valid C#
identifier, then the project name) and noting that the specification file
name does not influence the namespace.
Analyzer-Rules:
* Add the CLT category and a "Client Rules (CLT)" section documenting
ATC_API_CLT001 (error - two schemas generate the same type name under
`Single`) and ATC_API_CLT002 (warning - `clientName` is ignored because
granularity is `PerArea`).
Working-with-CSharp-Client:
* Add a "Client Granularity and Naming" section, including that an explicit
`clientName` is used verbatim and `clientSuffix` is not appended.
Working-with-CLI:
* Document the `--client-granularity` and `--client-name` options and the
matching `ApiGeneratorOptions` entries.
Cross-page anchors verified.
6deb8db
docs: add Working-with-CSharp-Client
eaac79d
docs: update OPR001 (operationId) with stricsmode for standard
ee99e11
Document rate-limit spec guards ATC_API_RL004-RL008
- Add all five to the rate limiting rules table with per-rule notes on why the
silent fallback is the dangerous behaviour
- Working-with-Rate-Limiting: new "Value rules the generator checks for you"
table after the extension reference, plus the callout that rate limiting is
switched off with x-ratelimit-enabled: false, never permit-limit: 0
- Add a prominent warning to the Disabling section that x-ratelimit-enabled is
operation-only and is not inherited, unlike every other x-ratelimit-*
- Cross-reference RL007 from the Retry-After section, noting it is evaluated
against the same first-wins policy set the generator emits
ac4789c
docs(rate-limiting): document per-algorithm Retry-After support)
4629301
Document ATC_API_RL003 and how to split a shared rate-limit policy
Prompted by feedback that the constraint was discoverable only by reading the
docs, and that the docs stated the rule without its consequence.
- Add RL003 to the rate limiting rules table, with a note on why only
explicitly-declared settings are compared
- Replace the terse "Consistent declarations" callout with a "One policy name =
one limiter" section explaining that this is an ASP.NET Core constraint
(a policy name is the unit of limiter registration), not a generator quirk
- Show the idiomatic inherit-without-repeating style that does NOT conflict
- Add a before/after example splitting one policy into two when endpoints need
different partitioning
- Warn that splitting also splits the budget, and that user/ip partitioning
multiplies it again per caller, so permit limits usually need re-tuning
- Clarify in Hierarchical Inheritance that the chain picks the policy name,
while the policy's settings come from the first declaring site
a6a9a34
Document rate-limiting diagnostics ATC_API_RL001 and RL002
- Add the RL category to the Categories table
- New Rate Limiting Rules (RL) section covering both warnings, with notes on why
the silent fallback is the less safe behaviour and on how RL002 respects the
operation -> path -> document inheritance chain
- Cross-reference both rules from the Partitioning section
fa50f00
Document rate-limit configure callback, Retry-After and partitioning
- Add the three new x-ratelimit-* extensions to the reference table
- New Partitioning section (global/ip/user), with the middleware-ordering
caveat: UseRateLimiter must run after UseAuthentication/UseAuthorization, and
forwarded headers must be honoured for ip behind a proxy
- Explain the user key fallback chain (the JWT handler remaps sub to
ClaimTypes.NameIdentifier via MapInboundClaims)
- New sections for the configure callback and for Retry-After, including the
aggregation rule: OnRejected is a single global assignment, so it is emitted
if any resolved policy enables the flag
- Fix the Response Headers section, which incorrectly claimed ASP.NET Core adds
Retry-After and the X-RateLimit-* family automatically. It adds none of them
- Update the Dependency Injection example to the new generated signature
0176ef9
docs: add note about Microsoft.OpenApi and severity vulnerability
b47da90
docs: add excludeFromCodeCoverage to marker-files and add Working-with-Code-Coverage
b8ba6f8
docs: add missing analyzer rules and cookie parameter FAQ
- Analyzer-Rules.md: add SCH014-SCH017, SCH019-SCH020 (OAS 3.1/3.2
schema rules), OPR026 (unsupported parameter style), SEC011
(mutualTLS info), and new STREAM category with STREAM001
- FAQ-and-Troubleshooting.md: add cookie parameter FAQ explaining
that ASP.NET Core has no [FromCookie] and how to read cookies
via HttpContext.Request.Cookies in handler implementations
16e4cca
docs: document --enum-runtime-values flag for Union enums
- Add --enum-runtime-values to CLI and TypeScript Client option tables
- Add runtime values section explaining the const array, UI list usage, and Zod/Enum-style interactions
85c6727
docs: document GEN012/GEN013/SCH018 rules and discriminator value convention
- Add ATC_API_GEN012 (handler shadows leftover scaffolded stub) and ATC_API_GEN013 (unparseable marker file falls back to defaults)
to GEN rules table
- Add ATC_API_SCH018 (distinct schema names sanitizing to the same C# identifier) to SCH rules table
- Clarify discriminator values default to verbatim schema names and correct the polymorphism example to match
b6e9a15
docs: document path filtering and inline parameter enum modes
- Add includePaths/excludePaths glob options to server and client tables
- Add Inline Parameter Enum Modes section with Enum/String values
- Note inlineParameterEnums "String" escape hatch for 1.0.252 breaking change
- Add tip on using path filters to split a spec across client projects
bf2952d
docs: expand TypeScript client coverage (hooks, branded IDs, Zod runtime, SignalR)
- Roadmap: reorganize TypeScript client section into Core / HTTP variants / Schemas / Hooks / Runtime / Spec / DX / Strategic categories; bump TS coverage to 60/60 and OpenAPI 3.1 to ~80%
- Home: add feature rows for React Query+SWR hooks, branded ID types, runtime Zod validation, and SignalR hub hooks
- Working-with-CLI: document --hooks-mode, --zod-runtime-validate, --branded-ids, --msw flags with new example invocations
- Working-with-TypeScript-Client: add sections for per-op result types, readOnly/writeOnly schema split, branded IDs, runtime Zod validation, useSuspenseQuery mode, multiple servers, webhook callbacks, SignalR hub hooks, discriminated unions, streaming hooks (useXxxStream, useInfiniteQuery), README + dual ESM/CJS scaffold
- Showcase-Demo: drop useAccountsStreaming.ts from sample tree; mark useNotificationHub.ts as slated for migration to generated x-signalr-hubs hooks
b75a3df