api-spec

KO | EN

gitlite — search

#javascript #hacktoberfest #llm #golang #machine-learning #nodejs #awesome #cli #kubernetes #awesome-list #vue #security #ios #mcp

(★ 11)

No description available.

api-spec Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Backstage AI API Spec Generator

An automated solution for generating OpenAPI specifications using AI within a Backstage developer portal.

## Overview

This project enables developers to automatically generate OpenAPI specifications by simply describing their API requirements. The system leverages Google's Gemini models to create valid OpenAPI 3.0 YAML files, which are then published to GitHub and registered in the Backstage catalog.

## Architecture

```
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Backstage UI  │────▶│  Scaffolder      │────▶│  Gemini API     │
│   (Template)    │     │  Custom Action   │     │  (Google AI)    │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌──────────────────┐
                        │  GitHub          │
                        │  (Repository)    │
                        └──────────────────┘
                               │
                               ▼
                        ┌──────────────────┐
                        │  Backstage       │
                        │  Catalog         │
                        └──────────────────┘
```

## Quick Start

### Prerequisites

- Node.js 18+
- Yarn 1.x (Classic)
- GitHub Personal Access Token
- Google Gemini API Key

### Installation

1. **Clone and install dependencies:**

```bash
   yarn install
   ```

2. **Configure environment variables:**

```bash
   cp .env.example .env
   ```

Edit `.env` and add your credentials:

```
   GEMINI_API_KEY=your-gemini-api-key-here
   GITHUB_TOKEN=ghp_your-token-here
   ```

3. **Start the development server:**

```bash
   yarn dev
   ```

4. **Open Backstage:**
   Navigate to http://localhost:3000

## Project Structure

```
api-spec/
├── packages/
│   └── backend/
│       └── src/
│           ├── plugins/
│           │   ├── scaffolder/
│           │   │   └── actions/
│           │   │       ├── gemini.ts      # Custom Gemini action
│           │   │       └── index.ts
│           │   └── scaffolder.ts          # Plugin registration
│           ├── types.ts                    # Type definitions
│           └── index.ts                    # Backend entry point
├── templates/
│   └── ai-api-spec/
│       ├── template.yaml                   # Software template
│       └── skeleton/
│           ├── README.md
│           └── .gitignore
├── app-config.yaml                         # Main configuration
├── app-config.local.yaml                   # Local dev config
└── package.json
```

## Configuration

### GitHub Integration

Add your GitHub token to `app-config.local.yaml`:

```yaml
integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}
```

### Template Registration

Templates are registered in `app-config.yaml`:

```yaml
catalog:
  locations:
    - type: file
      target: ../../templates/ai-api-spec/template.yaml
      rules:
        - allow: [Template]
```

## Using the Template

1. Navigate to **Create** in Backstage
2. Select **AI API Spec Generator**
3. Fill in the form:
   - **Service Name:** e.g., `inventory-service`
   - **API Description:** e.g., "REST API for inventory management with CRUD operations, authentication, and stock tracking"
   - **GitHub Owner:** Your organization or username
4. Click **Create**
5. The system will:
   - Generate an OpenAPI spec using AI
   - Create a new GitHub repository
   - Register the API in the Backstage catalog

## Custom Action Details

The `gemini:generate-spec` action:

- **Input:** `prompt` - Description of the API requirements
- **Output:** `specContent` - Generated OpenAPI YAML specification
- **Model:** Gemini 1.5 Pro (configurable)
- **Temperature:** 0.2 (for consistent output)

## Example Prompts

Here are some example prompts for generating API specs:

- "User authentication API with login, logout, password reset, and JWT token management"
- "E-commerce product catalog with categories, search, filtering, and pagination"
- "Real-time chat messaging API with WebSocket support and message history"
- "IoT sensor data collection API with batch uploads and time-series queries"

## Security Notes

- Never commit `.env` files with actual credentials
- Use GitHub Apps for production instead of PATs
- Restrict Gemini API key permissions if possible
- Review generated specs before deploying to production

## Resources

- [Backstage Documentation](https://backstage.io/docs)
- [OpenAPI Specification](https://swagger.io/specification/)
- [Google Gemini API Reference](https://ai.google.dev/docs)

api-spec

api-spec Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

api-spec

api-spec Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README