Summary
Swagger Editor is an excellent tool for designing OpenAPI specifications. Recently, many teams have started using AI assistants and other automation tools to help author and refactor API specifications.
Today, there is no generic way to integrate such tools into the editor without maintaining a fork or modifying its internal code.
Instead of adding support for any specific AI provider or service, I would like to propose a generic document transformation extension point.
Proposal
Introduce a plugin API that allows external tools to:
- read the current OpenAPI document;
- send it to an arbitrary backend service;
- receive an updated document (or a patch);
- apply the changes through the editor's existing APIs.
For example:
Swagger Editor
│
▼
Document Transformer Plugin
│
▼
Any backend service
│
▼
Updated document / JSON Patch
The backend could be:
- an internal enterprise service;
- an AI assistant;
- a custom OpenAPI linter;
- a refactoring tool;
- a documentation generator;
- a compliance checker;
- or any other document transformation service.
The editor itself would remain completely provider-agnostic.
Possible API
Something conceptually similar to:
registerDocumentTransformer({
id: "custom-transformer",
label: "Transform document",
transform(document: string): Promise<{
document?: string;
patch?: JsonPatch[];
}>
})The editor would simply expose the current specification and provide a supported way to replace or patch it.
Why this is useful
This feature is not limited to AI.
Potential use cases include:
- automatic endpoint generation;
- schema refactoring;
- style normalization;
- organization-specific conventions;
- automatic migration between OpenAPI versions;
- bulk renaming;
- custom validation and fixes;
- internal tooling.
Benefits
- No vendor lock-in.
- No dependency on a particular AI provider.
- Keeps secrets and authentication entirely on backend services.
- Allows enterprise deployments without exposing credentials to the browser.
- Avoids maintaining long-lived forks of Swagger Editor.
- Enables an ecosystem of reusable plugins.
(This text has been generated with AI)
Summary
Swagger Editor is an excellent tool for designing OpenAPI specifications. Recently, many teams have started using AI assistants and other automation tools to help author and refactor API specifications.
Today, there is no generic way to integrate such tools into the editor without maintaining a fork or modifying its internal code.
Instead of adding support for any specific AI provider or service, I would like to propose a generic document transformation extension point.
Proposal
Introduce a plugin API that allows external tools to:
For example:
The backend could be:
The editor itself would remain completely provider-agnostic.
Possible API
Something conceptually similar to:
The editor would simply expose the current specification and provide a supported way to replace or patch it.
Why this is useful
This feature is not limited to AI.
Potential use cases include:
Benefits
(This text has been generated with AI)