Drafting the Spec with AI
Kong's create-api.dev drafts an OpenAPI spec from a plain-English description, with no login or setup required. A developer documented using ChatGPT to generate an OpenAPI YAML spec from a list of endpoints; the output included summaries, descriptions, and example responses. Swagger also offers AI-assisted generation.
These tools lower the barrier to spec-first design, in which the contract is written before the implementation. The output is standard OpenAPI YAML or JSON, machine-readable and ready for tooling. A spec generated this way can be dropped into Swagger UI, used to generate client SDKs, or fed into a mock server. The tools do not build the backend. They do not enforce business rules. A spec is only as good as the details it captures. The value is speed: the drafting phase shrinks from manual typing to a single prompt, leaving more time for review.
Validation and Linting: Catching Errors Early
Generated specs need validation before they are used as contracts. Swagger Editor and spectral are the standard tools for this step. Swagger Editor provides a graphical interface for editing OpenAPI specs. Spectral runs from the command line, so it fits into automated CI checks. In the ChatGPT example, the initial spec produced only two errors when validated with an OpenAPI extension, and the author fixed both manually. The draft was close but not exact.
Linting catches structural problems: missing required fields, inconsistent parameter names, invalid response codes. A spec that fails linting will produce broken client code and confusing documentation. Spectral enforces standards through configurable rules that catch these issues before deployment.
Swagger positions AI generation inside a governed workflow, enforcing standards with style guides and linting tools like spectral. Kong's create-api.dev tracks spec quality with an evaluation system that starts with DeepEval, and it uses user feedback to improve its system prompt. The tool's own design acknowledges that output quality varies.
Handling Edge Cases: Enums, Errors, and Auth
AI-generated specs often fall short in the areas that matter most for integration. Precise enums, error response schemas, and authentication flows require specific details that a general prompt rarely supplies. For enums, the developer must list every valid value. For error responses, the spec needs a schema for each error code. For authentication, the security scheme must match the actual mechanism: API key, OAuth, or bearer token. A security scheme that does not match the implementation will cause authentication failures in production. For example, an OAuth flow requires token URLs and scopes, which are often omitted in a general description. A prompt that names these specifics produces a better draft than a general description.
That same ChatGPT example shows the pattern: the author iterated to add servers and other missing sections. Kong's create-api.dev supports uploading an existing spec or design doc to generate or modify a spec. Those decisions remain the developer's responsibility.
Integrating AI into Design-First Workflows
AI-assisted generation supports spec-first design, but it must be integrated with version control and review processes. That framing matters: the spec is the source of truth, and AI drafts are inputs to that source, not the source itself.
Human review is essential for business logic, naming conventions, and ensuring the spec matches actual API behavior. Reviewers should verify that security schemes and error responses align with the implementation. The review discipline mirrors what developers apply to AI-generated code in legacy codebases: verify every output against the system it describes. Version control also enables rollback if a change introduces a breaking contract. It also provides a history of changes, making it easy to track when a spec was modified. An AI draft is not automatically updated when code changes. A spec that drifts from the implementation breaks clients. The ChatGPT author found the spec a great starting point and refined it with the bot. That is the pattern: AI accelerates drafting, humans own the contract.
