feat: generate-spec command article#337
Conversation
![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 Agent has reviewed your changes and found 2 potential issue(s).
Note
Low Risk
This PR only adds a new documentation article and introduces no code or behavioral changes, resulting in zero operational risk.
Overview
Adds a new blog post introducing the experimental generate-spec command in the Redocly CLI. The article covers:
- How the command deterministically infers OpenAPI 3.1 descriptions from recorded HTTP traffic (such as HAR or Kong logs).
- A practical demonstration using the Redocly Cafe API as an example.
- Details on the optional
--with-aiflag, which refines baseline descriptions using AI providers like Claude, Codex, or Cursor. - Necessary warnings regarding data privacy and the command's experimental status.
|
|
||
| ```bash | ||
| redocly proxy --target https://api.cafe.redocly.com --har ./cafe.har | ||
| ``` |
There was a problem hiding this comment.
The proxy command records full HTTP exchanges, including credentials and PII. Move the 'Capture in a sandboxed environment' warning to the recording section to ensure users avoid capturing sensitive production data.
| {% admonition type="warning" name="Traffic leaves your machine" %} | ||
| `--with-ai` sends samples of the recorded traffic - URLs, query strings, request and response bodies - to the selected AI provider. | ||
| Capture in a sandboxed environment with synthetic data, and make sure the traffic contains no secrets or personal data you are not allowed to share. | ||
| {% /admonition %} |
There was a problem hiding this comment.
Deterministic inference can leak PII from traffic into the generated spec via enum values. Present the synthetic data advice as a general requirement for all modes, not just for AI-assisted refinement.
1 participant
What/Why/How?
A new article for
generate-speccommand in Redocly CLI. To be published oncedriftarticle lands (#332) and whengenerate-speccommand is released (Redocly/redocly-cli#2937)Reference
Testing
Screenshots (optional)
Check yourself
Security