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.
| title: No OpenAPI description yet? Generate one from real traffic | ||
| description: The new generate-spec command infers an OpenAPI description from recorded HTTP traffic - deterministically first, with optional AI refinement. | ||
| author: adam-sobaniec | ||
| publishedDate: "2026-07-15" |
There was a problem hiding this comment.
Date to be updated when we merge PR
| An OpenAPI description is the foundation that everything an agent touches is built on: reference docs, SDKs, MCP tools, request validation. | ||
| Without one, your API's capabilities are simply invisible to them. | ||
|
|
||
| So if your API doesn't have an OpenAPI description yet, this is a good moment to start. |
There was a problem hiding this comment.
I think the 2 previous paragraphs are too long intro for just this summary
| The command accepts HAR files, Kong logs, Nginx/Apache JSON logs, and NDJSON - a file or a whole folder of them. | ||
| Traffic parsing is shared with the [`drift` command](./catch-api-drift.md), so any log that works with `drift` works here too. | ||
|
|
||
| From the recorded exchanges it builds a baseline deterministically - no AI involved, same traffic in, same description out: |
There was a problem hiding this comment.
| From the recorded exchanges it builds a baseline deterministically - no AI involved, same traffic in, same description out: | |
| From the recorded exchanges it builds a baseline deterministically - no AI involved yet, same traffic in, same description out: |
| - Alternative body shapes for the same operation are preserved as `oneOf` variants, and object shapes that repeat across the document are extracted into `components/schemas`. | ||
| - String values are analyzed conservatively: consistent well-known patterns get a `format` (`uuid`, `date-time`, `email`, `uri`), and strings that only ever take a small set of repeated values become an `enum`. | ||
|
|
||
| ## Try it on the Cafe API |
There was a problem hiding this comment.
I would move "try it" section as the last one, many people may drop off on this step not reaching the main part
There was a problem hiding this comment.
oh, i see it's building up the story. Then maybe we don't ask them to try, as we are tyring it ourselves in this blog post. maybe we frame it as "here is the example usage (and you can try yourself too)"
| For everything determinism can't reach, add `--with-ai`: | ||
|
|
||
| ```bash | ||
| redocly generate-spec ./cafe.har --title "Cafe API" --with-ai --ai-provider claude -o cafe-openapi.yaml |
There was a problem hiding this comment.
do we have some kind of default provider or is --ai-provider required? just wondering
There was a problem hiding this comment.
Yes, claude is default provider.
| Flags, output, and behavior may change - including breaking changes - in upcoming releases while we shape it with your feedback. | ||
| {% /admonition %} | ||
|
|
||
| ## Get started |
There was a problem hiding this comment.
I think what we miss is some kind of comparison of --with-ai mode vs regular one or vs other open-source tools in this area.
|
Note: please don't review yet. I've converted to draft. Need to finalize this article. |
Co-authored-by: Adam Altman <adam@redocly.com>
Co-authored-by: Adam Altman <adam@redocly.com>
Co-authored-by: Adam Altman <adam@redocly.com>
Co-authored-by: Adam Altman <adam@redocly.com>
Co-authored-by: Adam Altman <adam@redocly.com>
3 participants
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