yao/openapi/docs/migration-guide.md

# OpenAPI Migration Guide

This guide helps developers migrate their Yao applications to use the new OpenAPI mode. OpenAPI mode enables OAuth 2.1 authentication, AI Agent integration, and other advanced features.

## Overview

When OpenAPI is enabled, your application gains:

- **OAuth 2.1 Authentication** - Industry-standard secure authentication
- **AI Agent Integration** - Built-in AI agent and chat capabilities
- **Knowledge Base** - Vector search and RAG support
- **MCP Protocol Support** - Model Context Protocol for AI tooling
- **API Hot Reload** - Update APIs without server restart

## Quick Start

### 1. Enable OpenAPI

Add the OpenAPI configuration to your `app.yao`:

```json
{
  "name": "My Application",
  "openapi": {
    "enabled": true,
    "baseURL": "/v1"
  }
}
```

### 2. Update Frontend API Calls

The API path prefix changes when OpenAPI is enabled:

| Before (Traditional) | After (OpenAPI)      |
| -------------------- | -------------------- |
| `/api/user/login`    | `/v1/api/user/login` |
| `/api/product/list`  | `/v1/api/product/list` |

**Recommended**: Use a configuration variable for the API prefix:

```javascript
// config.js
export const API_PREFIX = process.env.OPENAPI_ENABLED ? '/v1/api' : '/api';

// usage
fetch(`${API_PREFIX}/user/login`, { ... });
```

### 3. Update Authentication

Replace JWT tokens with OAuth tokens:

```javascript
// Before: JWT
fetch('/api/user/profile', {
  headers: {
    'Authorization': 'Bearer <jwt-token>'
  }
});

// After: OAuth
fetch('/v1/api/user/profile', {
  headers: {
    'Authorization': 'Bearer <oauth-access-token>'
  }
});
```

## Route Changes

### Route Structure

```
/{baseURL}/
├── api/          # Your custom APIs (isolated namespace)
│   ├── user/
│   ├── product/
│   └── ...
├── __yao/        # Built-in Widgets
│   ├── table/
│   ├── form/
│   ├── list/
│   ├── chart/
│   ├── dashboard/
│   └── sui/v1/
├── oauth/        # OAuth endpoints
├── agent/        # AI Agent
├── chat/         # Chat sessions
├── kb/           # Knowledge Base
└── ...           # Other system features
```

### Route Mapping Examples

Assuming `baseURL = "/v1"`:

| Type | Traditional Mode | OpenAPI Mode |
| ---- | ---------------- | ------------ |
| Custom API | `/api/user/login` | `/v1/api/user/login` |
| Table Widget | `/api/__yao/table/pet/search` | `/v1/__yao/table/pet/search` |
| Form Widget | `/api/__yao/form/pet/find/1` | `/v1/__yao/form/pet/find/1` |
| SUI Render | `/api/__yao/sui/v1/render/home` | `/v1/__yao/sui/v1/render/home` |
| OAuth Token | N/A | `/v1/oauth/token` |
| AI Agent | N/A | `/v1/agent/chat` |

## Authentication Changes

### Guard Mapping

Your existing guard configurations are automatically mapped:

| Guard Name | Traditional Mode | OpenAPI Mode |
| ---------- | ---------------- | ------------ |
| `bearer-jwt` | JWT Bearer Token | OAuth Access Token |
| `query-jwt` | JWT in Query String | OAuth Access Token |
| `cookie-jwt` | JWT in Cookie | OAuth Secure Cookie |
| `cookie-trace` | Session Tracking | OAuth Session |
| `-` (public) | No auth | No auth |

### No Code Changes Required

Your API definitions remain unchanged:

```json
{
  "name": "User API",
  "version": "1.0.0",
  "guard": "bearer-jwt",
  "paths": [
    {
      "path": "/profile",
      "method": "GET",
      "process": "scripts.user.Profile"
    }
  ]
}
```

The `bearer-jwt` guard automatically uses OAuth authentication when OpenAPI is enabled.

### Custom Guards

Custom guards defined via processes continue to work unchanged:

```json
{
  "guard": "scripts.auth.CustomGuard",
  "paths": [...]
}
```

### Public APIs

Public APIs (`guard: "-"`) work identically in both modes:

```json
{
  "guard": "-",
  "paths": [
    {
      "path": "/health",
      "method": "GET",
      "process": "scripts.health.Check"
    }
  ]
}
```

## OAuth Integration

### Obtaining Access Tokens

Use the OAuth token endpoint to obtain access tokens:

```bash
# Authorization Code Flow
curl -X POST /v1/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=<authorization_code>" \
  -d "client_id=<client_id>" \
  -d "redirect_uri=<redirect_uri>" \
  -d "code_verifier=<pkce_verifier>"
```

### Refreshing Tokens

```bash
curl -X POST /v1/oauth/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=<refresh_token>" \
  -d "client_id=<client_id>"
```

### Available OAuth Endpoints

| Endpoint | Method | Purpose |
| -------- | ------ | ------- |
| `/v1/oauth/authorize` | GET, POST | Authorization request |
| `/v1/oauth/token` | POST | Token exchange |
| `/v1/oauth/revoke` | POST | Revoke tokens |
| `/v1/oauth/introspect` | POST | Token introspection |
| `/v1/oauth/userinfo` | GET | User information |
| `/v1/oauth/jwks` | GET | JSON Web Key Set |

See [OAuth Documentation](./oauth.md) for complete endpoint reference.

## API Hot Reload

OpenAPI mode supports hot reloading of custom APIs without server restart.

### Triggering Hot Reload

After modifying `apis/*.http.yao` files:

**Option 1: Via API call**

```bash
curl -X POST /v1/api/__reload
```

**Option 2: Via Process**

```javascript
Process("yao.api.Reload");
```

**Option 3: Automatic (Development Mode)**

In development mode, file changes are automatically detected and APIs are reloaded.

### What Gets Reloaded

- Custom API definitions (`apis/*.http.yao`)
- Route mappings
- Guard configurations

### What Does NOT Get Reloaded

- Widget definitions (require restart)
- OpenAPI system routes
- Process/Script code (handled separately)

## SUI Frontend Integration

SUI pages work seamlessly with OpenAPI mode.

### Backend Script Calls

Update your SUI backend scripts to use the new API prefix:

```typescript
// pages/home/home.backend.ts
import { Process } from '@yao/runtime';

export function getData() {
  // Process calls remain unchanged
  return Process('models.user.Find', 1, {});
}
```

### Frontend API Calls

```html
<!-- pages/home/home.html -->
<script>
  // Use the configured API prefix
  const API_PREFIX = window.__yao?.apiPrefix || '/api';
  
  fetch(`${API_PREFIX}/user/profile`)
    .then(res => res.json())
    .then(data => console.log(data));
</script>
```

## Checklist

### Before Migration

- [ ] Back up your application
- [ ] Review all API endpoints in use
- [ ] Identify frontend API calls that need updating
- [ ] Plan OAuth client registration

### During Migration

- [ ] Enable OpenAPI in `app.yao`
- [ ] Update frontend API prefix configuration
- [ ] Register OAuth clients
- [ ] Test authentication flows
- [ ] Verify all API endpoints

### After Migration

- [ ] Remove legacy JWT token generation code
- [ ] Update documentation
- [ ] Train team on OAuth flows
- [ ] Monitor for authentication issues

## Troubleshooting

### 404 Not Found

**Symptom**: API returns 404 after enabling OpenAPI.

**Solution**: Update the API path to include the new prefix:

```javascript
// Wrong
fetch('/api/user/profile');

// Correct
fetch('/v1/api/user/profile');
```

### 401 Unauthorized

**Symptom**: API returns 401 with valid JWT token.

**Solution**: Use OAuth access token instead of JWT:

```javascript
// Wrong: Using old JWT
headers: { 'Authorization': 'Bearer <jwt-token>' }

// Correct: Using OAuth access token
headers: { 'Authorization': 'Bearer <oauth-access-token>' }
```

### CORS Issues

**Symptom**: CORS errors when calling APIs from frontend.

**Solution**: Ensure your OAuth client is registered with the correct redirect URIs and origins.

### Hot Reload Not Working

**Symptom**: API changes not reflected after modification.

**Solution**: 
1. Ensure you're in development mode
2. Manually trigger reload: `curl -X POST /v1/api/__reload`
3. Check for syntax errors in API definition files

## FAQ

### Can I use both JWT and OAuth?

No. When OpenAPI is enabled, all authentication uses OAuth. The JWT guards are automatically mapped to OAuth for backward compatibility.

### Do I need to modify my API definition files?

No. Your `apis/*.http.yao` files remain unchanged. The guard names are automatically mapped to the appropriate authentication method.

### What happens to existing JWT tokens?

Existing JWT tokens will no longer work. Users need to re-authenticate using OAuth.

### Can I disable OpenAPI after enabling it?

Yes. Remove or set `openapi.enabled: false` in `app.yao`. Note that this will break OAuth-dependent features.

### Is the performance impacted?

The performance impact is negligible (< 0.01%). The dynamic routing proxy adds approximately 0.1 microseconds per request.

## Related Documentation

- [OAuth Reference](./oauth.md) - Complete OAuth endpoint documentation
- [AI Agent Guide](./agent.md) - Using AI Agent features
- [Knowledge Base Guide](./kb.md) - Setting up Knowledge Base