Spec Auditor
Spec Audit scores your OpenAPI spec out of 10 for how well it builds an SDK, and lists every finding with the fix. Run it before your first build: a problem in the spec becomes a problem in all ten languages.
You can open it from either studio, or try it without an account on the public Spec Audit page.
What it checks
There are fourteen rules. Each one can cost part of the score, in proportion to how much of your spec it affects.
| Rule | Why it matters |
|---|---|
| Successful responses declare a schema | Without one, a method has no typed return value |
Shared models live in components and are $ref'd | Inline models become duplicated types |
| Generated public names do not collide | Two things with one name will not compile |
| Every path placeholder has a parameter | The method cannot fill in the URL |
Every operation declares an operationId | It is where method names come from |
operationIds read as method names | The name becomes part of your SDK's API |
| Operations carry a summary or description | It becomes the method's doc comment |
| Request bodies are documented | Callers need to know what to send |
| Failure responses are declared | Errors stay untyped otherwise |
| Operations are tagged | Tags group methods into namespaces |
| No duplicate or equivalent paths | Two routes compete for one method |
| Authentication is described | The client cannot sign requests otherwise |
| Parameters explain their purpose | The text becomes parameter documentation |
| A server URL is declared | The client needs a default address |
Working through findings
Findings are listed as a review queue, with their severity and how many operations each one touches.
- Fix it. Eight of the fourteen rules can be fixed for you. Apply a fix and it is written into the spec.
- Ignore it. If you have decided a finding does not matter for your API, mute it. It moves to the Ignored list, where you can find it again.
From the CLI, the same review is octri sdk audit, with apply and ignore for each finding.