AI for docs articles

learn/ai-for-docs/ai-api-design-backward-compatibility-risks.md

@@ -0,0 +1,103 @@
+---
+seo:
+ title: Use AI to review API design for backward compatibility risks
+ description: How to prompt an LLM to compare two OpenAPI versions for breaking changes, where human judgment ends, and how Redocly CLI plus Respect keep spec and live behavior aligned in CI.
+---
+
+# Use AI to review API design for backward compatibility risks
+
+Your public OpenAPI file is a promise to every client that already shipped. When a field disappears, a type tightens, or a path renames, the break often shows up first in someone else’s production log. A large language model can read two snapshots and narrate what changed. It is not a contract test. Pair that review with [API standards and governance](https://redocly.com/docs/cli/api-standards) in CI using [Explore Redocly CLI](https://redocly.com/docs/cli/), then let [Redocly Respect](https://redocly.com/docs/respect/) exercise critical workflows against a real server.
+
+This article covers what counts as breaking, how to prompt with two spec versions, and how CLI linting plus Respect’s Arazzo-aware runs complement AI judgment.
+
+## Why compatibility risk hides in large specs
+
+Breaking changes are not always obvious renames. Optional can become required, enums can lose values clients still send, or a response schema can drop a field your SDK exposed. Line-by-line YAML diffs fatigue humans fast. A model can hold both trees and highlight operations where caller behavior likely changed.
+
+The model may still hallucinate a reorder as a semantic change, or miss runtime behavior the spec never captured. Treat it as a reviewer that returns a prioritized list, and treat CI as the judge that fails the merge until the list is addressed or ruled out.
+
+## What counts as breaking for clients
+
+Agree with consumers what “breaking” means before you prompt: removed paths, renamed fields, stricter types, new required properties, changed status semantics, narrower enums. Additive changes still belong in a changelog but need not fail the gate.
+
+Have the model label each finding breaking, probably safe, or needs human decision. If some branches are additive-only, say that so new optional fields are not flagged as breaks.
+
+## How to prompt AI with two OpenAPI versions
+
+### Context block template
+
+Paste something shaped like this before the two files:
+
+```markdown {% process=false %}
+You are comparing two OpenAPI 3.1 documents for backward compatibility.
+
+Roles:
+- Document A: last published spec (tag v1.2.0).
+- Document B: candidate release on branch release/1.3.
+
+Consumer contract (plain language):
+- Mobile clients cache GET /users/{id} for 24 hours; removing any 200 response field they deserialize is breaking.
+- Webhooks must accept unknown JSON keys on callbacks.
+
+Tasks:
+1. List operations where request or response schemas narrowed for existing clients.
+2. List renamed or removed paths, parameters, and schema properties with JSON pointers when possible.
+3. Flag changes to error models that might alter client branching on status plus body shape.
+4. Output a table: change, breaking Y/N/uncertain, suggested mitigation (deprecation header, versioned path, dual-write period).
+```
+
+Paste both files with clear delimiters. If policy lives only in Slack, summarize it in the prompt instead of assuming the model knows your release train.
+
+### Review checklist for the model
+
+Cover default responses, shared components reused across tags, and discriminator or oneOf shapes where a variant disappeared. Require operationIds on each row so tickets map to generators and tests.
+
+## Where Redocly CLI takes over
+
+AI output is not policy until it becomes rules and CI. [Explore Redocly CLI](https://redocly.com/docs/cli/) applies the same [built-in rules](https://redocly.com/docs/cli/rules/built-in-rules) and custom rules on every commit, so repeated enum removals fail the build instead of reappearing in chat.
+
+Use the [guide to configuring a ruleset](https://redocly.com/docs/cli/guides/configure-rules) with `recommended` or `recommended-strict` as baseline, then encode your compatibility policy explicitly. The [lint command](https://redocly.com/docs/cli/commands/lint) also validates [What is Arazzo?](https://redocly.com/learn/arazzo/what-is-arazzo) files next to your OpenAPI roots.
+
+[Per-API configuration](https://redocly.com/docs/cli/configuration/apis) lets a public bundle stay stricter than an internal experimental service, similar to telling the model to ignore internal-only paths.
+
+## Where Respect takes over
+
+Specs can parse yet still misdescribe production. [Redocly Respect](https://redocly.com/docs/respect/) sends real requests and checks responses against OpenAPI and Arazzo expectations. [use cases for Respect](https://redocly.com/docs/respect/use-cases) include local runs, PR CI, and scheduled smoke tests against staging or production.
+
+Model the journeys that define compatibility: login then profile, create then poll, cancel then verify. When the server diverges from the description, Respect fails where a static diff would stay green. Use AI to summarize failure logs for humans, not to skip the run.
+
+## What AI cannot prove
+
+A model cannot prove every client tolerates a change. It does not execute your stack or know compensating behavior inside mobile apps. It should not be the only gate when SLAs attach to specific response shapes.
+
+Use AI to widen spec review, Respect to bind descriptions to deployed behavior, and humans for intentional breaks with explicit version bumps.
+
+## Best practices
+
+1. Always pass two concrete artifacts, for example bundled YAML from `main` and from your release branch, not a vague “what changed lately” question.
+2. Ask for JSON pointers or operationIds so tickets map cleanly to engineering work.
+3. Encode repeated AI findings as rules so the same mistake cannot return unnoticed.
+4. Keep Arazzo workflows short and focused on compatibility-critical paths so CI stays fast and failures are interpretable.
+
+## What this approach cannot replace
+
+This approach cannot replace consumer-driven contract tests owned by client teams, canary analysis, or database migration review when behavior shifts outside HTTP. It is a structured spec review plus deterministic tooling, not a full release certification.
+
+## How the pieces fit together
+
+```mermaid
+graph LR
+  A[OpenAPI A plus OpenAPI B] --> B[LLM compatibility review]
+  B --> C[Human updates spec and rules]
+  C --> D[Redocly CLI lint]
+  D --> E[Respect Arazzo runs]
+  E --> F[CI or scheduled gate]
+```
+
+AI widens the diff narrative. Redocly CLI enforces the spec text. Respect checks that the running API still honors the workflows your clients depend on.
+
+## Learn more
+
+Start with [Explore Redocly CLI](https://redocly.com/docs/cli/) for [API standards and governance](https://redocly.com/docs/cli/api-standards), [built-in rules](https://redocly.com/docs/cli/rules/built-in-rules), and the [lint command](https://redocly.com/docs/cli/commands/lint) on every change.
+
+Add [Redocly Respect](https://redocly.com/docs/respect/) and [use cases for Respect](https://redocly.com/docs/respect/use-cases) when you need PR or scheduled runs that still fail if the live API drifts while the YAML stays valid.

learn/ai-for-docs/ai-auth-authorization-patterns.md

@@ -0,0 +1,146 @@
+---
+seo:
+ title: Use AI to check authentication and authorization patterns
+ description: Spot missing scopes, inconsistent security schemes, and thin auth error docs in OpenAPI with a model, then enforce fixes with Redocly CLI lint before merge.
+---
+
+# Use AI to check authentication and authorization patterns
+
+You can ask a model to read your OpenAPI security model before handlers ship, then run the same file through Redocly CLI lint in the pull request. The learn article [Use AI to accelerate and improve reviews](https://redocly.com/learn/ai-for-docs/ai-reviews) covers the wider review pattern; here the focus stays on schemes, scopes, route coverage, and the error contracts integrators need when credentials fail.
+
+## Why auth and authorization drift in API descriptions
+
+Teams add endpoints faster than they update `components.securitySchemes`. One route still documents API keys while the rest moved to OAuth2. Admin paths inherit a global bearer scheme but never list the scopes a caller needs. Documentation mentions 401 and 403 in prose while the spec only declares a generic 400.
+
+A model can compare many paths at once and ask whether each operation matches the story you tell about roles and trust boundaries. It does not replace threat modeling, but it gives you a patient reader for long YAML.
+
+## Inputs that keep the review grounded
+
+Paste a short auth model in plain language before the spec excerpt. Name actors (for example integrators, support staff, machine clients), which routes are public, and which actions require elevated roles.
+
+List invariants you already enforce in code, such as tenant isolation on every read, or that destructive verbs always require an admin scope. If the file is large, scope the excerpt to the surface you are changing and describe the rest in a sentence.
+
+### Auth context block you can paste
+
+```markdown {% process=false %}
+Auth model: OAuth2 client credentials for integrators; session cookies for the dashboard.
+Public: GET /status, GET /openapi.json
+Roles: reader (read-only), admin (write + delete)
+
+Review securitySchemes, security requirements, and auth-related responses:
+[paste OpenAPI excerpt]
+```
+
+## Prompt skeleton for auth and authorization
+
+Keep the ask structured so findings are easy to triage.
+
+```markdown {% process=false %}
+You are reviewing authentication and authorization for [one sentence domain].
+
+Please list:
+1. Operations that should require credentials but have no security requirement.
+2. Mismatches between security scheme names in operations and components.securitySchemes.
+3. Missing or inconsistent OAuth scopes (or permissions) across related endpoints.
+4. Operations that share a scheme but should differ by role or scope.
+5. Missing or vague 401 and 403 responses, including whether examples match the scheme.
+6. Public routes that should explicitly document security: [] if they are intentionally open.
+
+[paste OpenAPI or notes]
+```
+
+## Signals models often surface
+
+Across teams, reviews tend to cluster on a short set of themes. Orphan schemes appear when `components.securitySchemes` defines a name operations never reference. Scope gaps show up when write endpoints document fewer scopes than read endpoints on the same resource. Error gaps cluster when only 200 responses are declared, or when 401 and 403 reuse the same schema without explaining retry versus forbidden. Inheritance confusion happens when a global `security` block hides which routes are actually public.
+
+Treat the list as a prioritized backlog, not a verdict. Some routes are intentionally open, and some schemes are legacy until a migration finishes.
+
+## Thin before and after on security
+
+Before:
+
+```yaml {% process=false %}
+paths:
+  /reports:
+    get:
+      summary: Download usage report
+      security:
+        - bearerAuth: []
+components:
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+```
+
+After:
+
+```yaml {% process=false %}
+paths:
+  /reports:
+    get:
+      summary: Download usage report
+      security:
+        - BearerAuth: [reports:read]
+      responses:
+        '401':
+          description: Missing or invalid bearer token
+        '403':
+          description: Caller lacks reports:read scope
+components:
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+```
+
+The second sketch does not prove your threat model is complete, but it shows how a review nudges you toward aligned names, explicit scopes, and distinct failure responses before implementation hardens the wrong shape.
+
+```mermaid
+graph LR
+  A[Auth model plus OpenAPI] --> B[Model review]
+  B --> C[Human edits]
+  C --> D[redocly lint]
+  D --> E[Pull request]
+```
+
+Run the loop while the document is still cheap to edit.
+
+## Where CLI lint takes over
+
+When you accept changes, run the [lint command](https://redocly.com/docs/cli/commands/lint) against the same file the model saw. Lint applies preprocessors and rules, reports problems in OpenAPI and related formats, and does not run decorators, which keeps this step focused on spec compliance rather than publishing transforms.
+
+The [built-in rules](https://redocly.com/docs/cli/rules/built-in-rules) catalog includes security-related checks. The [security-defined rule](https://redocly.com/docs/cli/rules/oas/security-defined) verifies that every operation or global security requirement is defined. If an API is intentionally public, the rule documentation shows declaring an empty requirement so readers know the omission is deliberate:
+
+```yaml {% process=false %}
+security: []
+```
+
+In continuous integration, point the same command at pull requests so every spec edit repeats local checks. Models sometimes suggest scheme names or extensions your ruleset has not whitelisted yet, and lint surfaces those mismatches early.
+
+If you have no local config yet, the command defaults to the [recommended ruleset](https://redocly.com/docs/cli/rules/recommended). As standards mature, add [configurable rules](https://redocly.com/docs/cli/rules/configurable-rules) for org-specific auth policies, such as requiring scope text in operation descriptions or forbidding duplicate scheme types on one path. The [guide to configuring a ruleset](https://redocly.com/docs/cli/guides/configure-rules) walks through a practical baseline.
+
+Organizations that treat OpenAPI as law usually centralize how rules are authored and shared. The [API standards and governance](https://redocly.com/docs/cli/api-standards) page describes using the same configuration locally and in automation so developers see the same violations everywhere.
+
+## Best practices
+
+Ship the auth model as a short checklist, not a long policy essay, in the same message as the spec excerpt.
+
+Review one theme at a time on large files: scheme names first, then scopes, then error responses.
+
+Log model findings as tickets with path and operation anchors so humans can accept or reject with traceability.
+
+Combine model passes with deterministic tools so subjective completeness meets objective gates, which mirrors the guidance in [Use AI to accelerate and improve reviews](https://redocly.com/learn/ai-for-docs/ai-reviews).
+
+## What this pairing cannot replace
+
+Models do not know your live identity provider configuration, token lifetimes, or penetration test results unless you state them. They can suggest scopes that sound reasonable but do not match what your authorization service enforces. Lint cannot judge whether a scope is too broad for a role; it checks that the document obeys the rules you configured.
+
+## Summary
+
+Use a structured prompt plus a plain-language auth model to surface scheme, scope, and error gaps early, then let Redocly CLI enforce the rules your team already agreed to. Keep humans in the loop for trade-offs, and treat automation as a safety net rather than a substitute for security review.
+
+## Learn more
+
+When you are ready to wire the deterministic side of the loop, start with [Explore Redocly CLI](https://redocly.com/docs/cli/) for installation, first commands, and how lint fits alongside bundling and preview workflows described in the broader [rulesets](https://redocly.com/docs/cli/rules) documentation.