OpenAPIDesigner
A visual OpenAPI 3.1 specification designer built with React. Design, edit, and preview your API documentation โ all in one component.
English ยท ็ฎไฝไธญๆ ยท Live Demo ยท Documentation
Table of Contents
Features
- Visual Editor โ Design API endpoints, schemas, parameters, and responses through an intuitive UI
- Code Editor โ Built-in YAML/JSON editor with syntax highlighting
- Bidirectional Sync โ Visual and code editors stay in sync automatically
- Schema Designer โ Full JSON Schema support including
oneOf, allOf, anyOf, and not
- Security Schemes โ OAuth2, JWT, API Key, HTTP Basic, OpenID Connect, Mutual TLS
- Live Validation โ Real-time validation against the OpenAPI 3.1 specification
- API Documentation Preview โ Swagger UIโstyle documentation preview
- Import / Export โ Load and save specifications in YAML or JSON
- Internationalization โ Chinese and English out of the box
- Themes โ Dark and light themes with seamless switching
- Undo / Redo โ Full history support for all edits
- Tags Management โ Organize endpoints with tags
- Command Palette โ Quick navigation and actions via keyboard shortcut
Quick Start
Installation
npm install @xcan-cloud/open-api-designer
Basic Usage
import { OpenAPIDesigner } from '@xcan-cloud/open-api-designer';
function App() {
return (
<OpenAPIDesigner
defaultLocale="en"
defaultTheme="light"
onChange={(doc) => console.log(doc)}
/>
);
}
Using a Starter Document
import { OpenAPIDesigner, createPetStoreDocument } from '@xcan-cloud/open-api-designer';
function App() {
return (
<OpenAPIDesigner
initialDocument={createPetStoreDocument()}
onChange={(doc) => console.log(doc)}
/>
);
}
API Reference
<OpenAPIDesigner /> Props
| Prop |
Type |
Default |
Description |
initialDocument |
OpenAPIDocument |
undefined |
Pre-populated OpenAPI document to load on mount |
defaultLocale |
'zh' | 'en' |
'en' |
UI language |
defaultTheme |
'light' | 'dark' |
'light' |
Color theme |
onChange |
(doc: OpenAPIDocument) => void |
undefined |
Callback fired on every document change |
className |
string |
undefined |
Additional CSS class applied to the root element |
TypeScript Interface
interface OpenAPIDesignerProps {
initialDocument?: OpenAPIDocument;
defaultLocale?: 'zh' | 'en';
defaultTheme?: 'light' | 'dark';
onChange?: (doc: OpenAPIDocument) => void;
className?: string;
}
Exported Utilities
| Function |
Description |
createDefaultDocument() |
Returns a minimal, valid OpenAPI 3.1 document |
createPetStoreDocument() |
Returns a feature-rich Pet Store example document |
Component Architecture
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ OpenAPIDesigner โ
โ โ
โ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Toolbar โ โ Command Palette โ โ
โ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ
โ โโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Visual Editor โ Code Editor โ โ
โ โ โ (YAML / JSON) โ โ
โ โ โข Paths โ โ โ
โ โ โข Schemas โ โ โ
โ โ โข Parameters โโโโโ Bidirectional โโโโบโ โ
โ โ โข Responses โ Sync โ โ
โ โ โข Security โ โ โ
โ โ โข Tags โ โ โ
โ โโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ
โ โโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Validation โ Documentation โ โ
โ โ Panel โ Preview โ โ
โ โโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Sub-Projects
| Directory |
Description |
example/ |
Example demo application showcasing component usage |
website/ |
Documentation website with guides and API docs |
Customization
Loading a Custom Document
const myDoc: OpenAPIDocument = {
openapi: '3.1.0',
info: { title: 'My API', version: '1.0.0' },
paths: {},
};
<OpenAPIDesigner initialDocument={myDoc} />;
Adding Languages
The built-in i18n system supports Chinese (zh) and English (en). To contribute a new locale:
- Create a new locale file under
src/app/components/openapi-designer/i18n/.
- Copy an existing locale (e.g.,
en.ts) and translate all keys.
- Register the locale in the i18n configuration.
- Submit a pull request.
Technology Stack
| Category |
Technologies |
| Framework |
React 18, TypeScript |
| Styling |
Tailwind CSS v4 |
| UI Components |
Radix UI (shadcn/ui) |
| Icons |
Lucide React |
| YAML Processing |
js-yaml |
| Build Tool |
Vite |
Browser Support
| Browser |
Supported Version |
| Chrome |
Last 2 versions |
| Firefox |
Last 2 versions |
| Safari |
Last 2 versions |
| Edge |
Last 2 versions |
Contributing
Contributions are welcome! Please follow these steps:
- Fork the repository.
- Create a feature branch:
git checkout -b feat/my-feature.
- Commit your changes:
git commit -m 'feat: add my feature'.
- Push to the branch:
git push origin feat/my-feature.
- Open a pull request.
Please make sure your code passes the existing linting and build checks before submitting.
License
MIT ยฉ OpenAPIDesigner Contributors