openapi-rest-admin

v0.6.0

Published

6 months ago

A REST API admin interface built with React and OpenAPI

0High
0Medium
0Low

saltbo

openapi rest admin react api

What is OpenAPI Rest Admin?

OpenAPI Rest Admin is a Single Page Application that automatically creates admin interfaces from your OpenAPI/Swagger specifications. Point it to your API documentation, and get a fully functional admin panel with tables, forms, and CRUD operations - no coding required.

Key Benefits

Zero Setup: Works entirely in the browser, no backend needed
Automatic UI: Generates tables and forms from your API schemas
Modern Stack: Built with React 19, TypeScript, and Ant Design
Production Ready: Deploy as static files anywhere

How It Works

Provide OpenAPI Spec: Configure your OpenAPI document URL
Auto-Discovery: The app analyzes your API to identify resources
Generate Interface: Creates tables, forms, and navigation automatically
Direct API Calls: Makes HTTP requests directly to your API endpoints

🚀 Quick Start

Prerequisites

Node.js 18+ and npm

Installation

Clone and install

git clone https://github.com/your-username/openapi-rest-admin.git
cd openapi-rest-admin
npm install

Configure your API

Create a .env file:

# Your OpenAPI specification URL
VITE_OPENAPI_DOC_URL=https://your-api.com/openapi.json

# Optional: Custom title
VITE_APP_TITLE=My API Admin

Start development server
```
npm run dev
```
Open http://localhost:5173

Try with the Example REST Server

The project includes a demo REST server that provides a complete RESTful API with Authors, Books, and Notes resources:

Start the example server
```
cd example/simple-rest-server
chmod +x start.sh
./start.sh
```
The server will run at http://localhost:3000 with API documentation available at http://localhost:3000/api-docs

Configure the admin interface to use it

# In your .env file
VITE_OPENAPI_DOC_URL=http://localhost:3000/openapi.json

Open the admin interface at http://localhost:5173

This example server includes full CRUD operations for multiple resources and serves as an excellent demonstration of OpenAPI Admin's capabilities.

📜 Available Scripts

| Command | Description |
|---------|-------------|
| `npm run dev` | Start development server |
| `npm run build` | Build for production |
| `npm run test` | Run tests with Vitest |
| `npm run test:ui` | Run tests with interactive UI |
| `npm run typecheck` | TypeScript type checking |
| `npm run config:generate` | Generate configuration files |

⚙️ Configuration

Environment Variables

Create a .env file in the project root:

# Required: Your OpenAPI document URL
VITE_OPENAPI_DOC_URL=https://your-api.example.com/openapi.json

# Optional: Custom application title
VITE_APP_TITLE=My API Admin

Runtime Configuration

You can also configure the application at runtime by editing public/config.json:

{
  "openapiDocUrl": "https://your-api.example.com/openapi.json",
  "appTitle": "My API Admin"
}

Configuration Priority

The application loads configuration in the following order:

Environment variables (highest priority)
Default values

� Standalone Usage (Script Tag)

You can use OpenAPI Rest Admin as a standalone library, similar to Scalar API Reference:

Quick Setup

Build the standalone version
```
npm run build:standalone
```

Use in your HTML

<!DOCTYPE html>
<html>
<head>
    <title>My API Admin</title>
    <link rel="stylesheet" href="path/to/openapi-rest-admin.css">
</head>
<body>
    <div id="app"></div>
    <script src="path/to/openapi-rest-admin.js"></script>
    <script>
        OpenAPIRestAdmin.createAdminInterface('#app', {
            openapiDocUrl: 'https://api.example.com/openapi.json',
            siteTitle: 'My API Admin'
        });
    </script>
</body>
</html>

For complete standalone usage documentation, see docs/STANDALONE_USAGE.md.

�🚀 Production Deployment

Static File Hosting

Build the application
```
npm run build
```

Deploy to any static hosting

# Copy built files to your web server
cp -r build/client/* /var/www/html/

# Or use a static file server
npx serve build/client

Update configuration

Edit config.json in your deployed files:

{
  "openapiDocUrl": "https://your-production-api.com/openapi.json",
  "appTitle": "Production API Admin"
}

Docker Deployment

# Dockerfile included in the project
docker build -t openapi-rest-admin .
docker run -p 5173:5173 openapi-rest-admin

🔧 Supported OpenAPI Features

Resource Detection

Standard REST patterns (GET, POST, PUT, DELETE)
Path parameters (/users/{id})
Query parameters (filtering, pagination)
Request/response schemas

Schema Support

Basic types (string, number, boolean)
Complex types (objects, arrays)
Validation (required fields, formats, enums)
Example values

� Troubleshooting

Common Issues

CORS Errors: Ensure your API allows cross-origin requests
Invalid Schema: Check that your OpenAPI spec is valid JSON/YAML
No Resources Found: Verify your spec contains standard REST patterns
Config Loading Failed: Check browser console for errors

Debug Mode

localStorage.setItem("debug", "openapi-rest-admin:*");

🤝 Contributing

See CONTRIBUTING.md for detailed guidelines.

Quick start for contributors:

Fork and clone the repository
Run npm install and npm run dev
Make your changes and add tests
Submit a pull request

License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

React Router v7 - Routing and SSR
Ant Design - UI components
swagger-parser - OpenAPI parsing

Made with ❤️ for the API development community