AI for docs articles#308
Conversation
Consolidate the AI-for-docs article set onto the current upstream main so it can be reviewed as one cohesive change.
Replace the 1200x630 thumbnail SVG with a 378x112 cropped variant matching the other learning cards, and trim the visible items to five with an explicit "13 more topics" overflow indicator.
![redocly[bot]](https://avatars.githubusercontent.com/in/348054?s=60&v=4){kind=small}
There was a problem hiding this comment.
marketing-site AI Review: 🟢 Completed
Reunite Bot has reviewed your changes and found 3 potential issue(s).
Note
Low Risk
The changes only affect static documentation content and learning center UI configuration (markdown files, SVG images, and card links). There are no modifications to core logic or infrastructure, meaning the risk of breaking functionality is negligible.
Overview
Adds 17 new articles to the learn/ai-for-docs/ directory detailing various practical use cases for AI in API documentation, such as automated PR reviews, backward compatibility checks, and usability testing.
Additionally, updates the "AI for Docs" card in pages/learning-center/cards.ts to surface the new articles, adjusts the moreItems count, and replaces the learning center thumbnail with a new cropped SVG (ai-for-docs-thumbnail-cropped.svg).
Co-authored-by: Adam Altman <adam@rebilly.com>
|
|
||
| # 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. |
There was a problem hiding this comment.
Mentions 'Redocly Respect' and uses invalid URLs instead of the correct product name 'Respect Monitoring' and its documentation path under Reunite.
|
|
||
| [Respect](https://redocly.com/respect) runs API workflows described in Arazzo against real environments. You define steps such as obtain token, create resource, list with pagination, and assert status codes and JSON shapes. Schedule those workflows against staging and production, and route failures to Slack or email the way you route test failures. | ||
|
|
||
| [Respect use cases](https://redocly.com/docs/respect/use-cases) cover contract testing in pull requests and ongoing monitoring after deploy. The same workflow file can gate a release in CI and run hourly to detect silent regressions. |
There was a problem hiding this comment.
Mentions 'Respect' and uses invalid URLs like 'redocly.com/respect' instead of the correct product name 'Respect Monitoring' and its documentation path under Reunite.
|
|
||
| ## Runtime gaps with Respect | ||
|
|
||
| Some gaps appear only when code ships: response fields differ from the schema, status codes change, or sandbox behavior diverges from production. [Respect](https://redocly.com/respect) and [Respect use cases](https://redocly.com/docs/respect/use-cases) include running Arazzo workflows on a schedule against live endpoints and alerting when results diverge from the spec you publish. |
There was a problem hiding this comment.
Mentions 'Respect' and uses invalid URLs like 'redocly.com/respect' and '/docs/respect/use-cases' instead of the correct product name 'Respect Monitoring' and its documentation path.
2 participants
What/Why/How?
Reference
Testing
Screenshots (optional)
Check yourself
Security