Back to "LLMApi: OpenAPI Генератор динамічного мока : Завантаження будь-якого спектру МSK2 Мок будь-який API"

This is a viewer only at the moment see the article on how this works.

To update the preview hit Ctrl-Alt-R (or ⌘-Alt-R on Mac) or Enter to refresh. The Save icon lets you save the markdown file to disk

This is a preview from the server running through my markdig pipeline

AI AI-Article API ASP.NET Core LLM LLMApi mockllmapi Nuget SignalR

LLMApi: OpenAPI Генератор динамічного мока : Завантаження будь-якого спектру МSK2 Мок будь-який API

Wednesday, 05 November 2025

NOTA: Ця стаття, в основному, створена штучною inteligenцією як частина мого пакету неджетів, як релізова документація.

Введение

Чи ви коли-небудь хотіли протестувати API, яке ще не було розроблено?' не підготовано до тесту? ? Чи ви хотіли розробити бездротовий тест, не заважаючи обмеженням швидкості? МSK2 Генератор динамічного макка OpenAPI дозволяє завантажити будь-яку спецификацію OpenAPI і миттєво створювати повністю?МSK3функціональний макк API з реалістичними даними?

Ніяких файлів конфігурації. Ніхто не створив ручних кінцевих точок

NuGet NuGet

Ви можете знайти Тут GitHub для проекту, всі громадські домени і т.д.

Менеджер OpenApi

Проблема: Розробка блоків API Dependencies

Сучасні застосування залежать від десятків зовнішніх API. Під час розробкиM SK1 ви стикаєтеся з багатьма проблемами

graph TD
    A[Your App] --> B{External API}
    B -->|Not Ready| C[Development Blocked]
    B -->|Rate Limited| D[Can't Test Freely]
    B -->|Requires Auth| E[Complex Setup]
    B -->|Expensive| F[Cost Concerns]
    B -->|Unreliable| G[Flaky Tests]

Традиційні рішення включають

  • Ручно пишемо макетні відповіді (потрібноM SK1 стає застарілим)
  • Запису/випромінювання HTTP-траficу МSK1маленькеM SK2важко підтримувати)
  • Використовуючи зашифровані пристрої (нереальним , не закриває

Рішення: Динамічне копування OpenAPI

Навімкніть систему на будь-яку функцію OpenAPI , і вона автоматично :

  1. Розшифровує спецификацію
  2. Відкриє всі кінцеві точки
  3. генерує реальні моделі даних, використовуючи LLM
  4. Використовує модель API на вашому локальному машині
sequenceDiagram
    participant Dev as Developer
    participant System as Mock System
    participant Spec as OpenAPI Spec
    participant LLM as Local LLM

    Dev->>System: Load spec from URL/file
    System->>Spec: Parse OpenAPI document
    Spec-->>System: Endpoints, schemas, descriptions
    System->>System: Register dynamic routes

    Dev->>System: GET /petstore/pet/123
    System->>LLM: Generate data for "Pet" schema
    LLM-->>System: Realistic pet data
    System-->>Dev: {"id": 123, "name": "Max", ...}

Як це працює

Уявлення про архітектуру

Система OpenAPI складається з кількох координованих компонентів:

graph TB
    A[HTTP Request] --> B{Route Matches?}
    B -->|No| C[404 Not Found]
    B -->|Yes| D[DynamicOpenApiManager]
    D --> E[Find Matching Endpoint]
    E --> F[OpenApiRequestHandler]
    F --> G[Extract Schema from Spec]
    G --> H[Build LLM Prompt]
    H --> I[PromptBuilder]
    I --> J[Include Context?]
    J -->|Yes| K[OpenApiContextManager]
    J -->|No| L[LLM Client]
    K --> L
    L --> M[Get Response]
    M --> N[JsonExtractor]
    N --> O[Return Mock Data]

Ключові компоненти:

  1. Динамічний OpenApiManager - Manages loaded specs and route matching
  2. OpenApiSpecLoader - Переносить та аналізує документи OpenAPI
  3. OpenApiRequestHandler - генерує відповіді для відповідних кінцевих точок
  4. Промпт-будівник - Створює LLM прохання з схемами OpenAPI
  5. OpenApiContextManager - Утримує послідовність всіх дзвінків

Завантаження specyfikацій

Спекти можна завантажити з трьох джерел:

1. Віддалений URL

POST /api/openapi/specs
Content-Type: application/json

{
  "name": "petstore",
  "source": "https://petstore3.swagger.io/api/v3/openapi.json",
  "basePath": "/petstore"
}

2. локальний файл

POST /api/openapi/specs
Content-Type: application/json

{
  "name": "my-api",
  "source": "./specs/my-api.yaml",
  "basePath": "/api/v1"
}

3. URL даних База МSK2 Кодований МSK3

POST /api/openapi/specs
Content-Type: application/json

{
  "name": "inline-api",
  "source": "data:application/json;base64,eyJvcGVuYXBpIjoiMy...",
  "basePath": "/api"
}

Визначати процес завантаження

Ось що стається, коли завантажуєш спецификацію

public async Task<SpecLoadResult> LoadSpecAsync(
    string name,
    string source,
    string? basePath = null,
    string? contextName = null)
{
    // 1. Use scoped service factory for OpenApiSpecLoader
    using var scope = _scopeFactory.CreateScope();
    var specLoader = scope.ServiceProvider
        .GetRequiredService<OpenApiSpecLoader>();

    // 2. Load the OpenAPI document
    var document = await specLoader.LoadSpecAsync(source);

    // 3. Determine base path from spec or parameter
    var effectiveBasePath = basePath
        ?? document.Servers?.FirstOrDefault()?.Url
        ?? "/api";

    // 4. Store spec with configuration
    var config = new OpenApiSpecConfig
    {
        Name = name,
        Source = source,
        Document = document,
        BasePath = effectiveBasePath,
        ContextName = contextName,
        LoadedAt = DateTimeOffset.UtcNow
    };

    _specs.AddOrUpdate(name, config, (_, __) => config);

    // 5. Notify listeners via SignalR
    await NotifySpecLoaded(name, effectiveBasePath);

    return new SpecLoadResult
    {
        Name = name,
        BasePath = effectiveBasePath,
        EndpointCount = CountEndpoints(document),
        Success = true
    };
}

Динамичне співпадіння маршрутів

Коли приходить прохання, система співставляє його з усіма завантаженнями

public OpenApiEndpointMatch? FindMatchingEndpoint(string path, string method)
{
    // Try each loaded spec
    foreach (var spec in _specs.Values)
    {
        // Remove base path prefix
        var relativePath = path;
        if (path.StartsWith(spec.BasePath))
        {
            relativePath = path.Substring(spec.BasePath.Length);
        }

        // Find matching path in OpenAPI document
        var (pathTemplate, operation) = FindOperation(
            spec.Document,
            relativePath,
            method);

        if (operation != null)
        {
            return new OpenApiEndpointMatch
            {
                Spec = spec,
                PathTemplate = pathTemplate,
                Operation = operation,
                Method = ParseMethod(method)
            };
        }
    }

    return null;
}

Обробка запитів

Як тільки з 'являється відповідний кінцевий пункт,, об' єкт генерує відповідьM SK1

public async Task<string> HandleRequestAsync(
    HttpContext context,
    OpenApiDocument document,
    string path,
    OperationType method,
    OpenApiOperation operation,
    string? contextName = null,
    CancellationToken cancellationToken = default)
{
    // 1. Extract request body
    var requestBody = await ReadRequestBodyAsync(context.Request);

    // 2. Get success response schema
    var shape = ExtractResponseSchema(operation);

    // 3. Get context history if using contexts
    var contextHistory = !string.IsNullOrWhiteSpace(contextName)
        ? _contextManager.GetContextForPrompt(contextName)
        : null;

    // 4. Build prompt from OpenAPI metadata
    var description = operation.Summary ?? operation.Description;
    var prompt = _promptBuilder.BuildPrompt(
        method.ToString(),
        path,
        requestBody,
        new ShapeInfo { Shape = shape },
        streaming: false,
        description: description,
        contextHistory: contextHistory);

    // 5. Get response from LLM
    var rawResponse = await _llmClient.GetCompletionAsync(
        prompt,
        cancellationToken);

    // 6. Extract clean JSON
    var jsonResponse = JsonExtractor.ExtractJson(rawResponse);

    // 7. Store in context if configured
    if (!string.IsNullOrWhiteSpace(contextName))
    {
        _contextManager.AddToContext(
            contextName,
            method.ToString(),
            path,
            requestBody,
            jsonResponse);
    }

    return jsonResponse;
}

Видобуток шеми

Система витягує схему реакції з визначення OpenAPI:

private string? ExtractResponseSchema(OpenApiOperation operation)
{
    // Look for successful response (2xx)
    var successResponse = operation.Responses
        .FirstOrDefault(r => r.Key.StartsWith("2"))
        .Value;

    if (successResponse == null)
        return null;

    // Get JSON content
    var jsonContent = successResponse.Content
        .FirstOrDefault(c => c.Key.Contains("json"))
        .Value;

    if (jsonContent?.Schema == null)
        return null;

    // Convert OpenAPI schema to JSON Schema
    return ConvertToJsonSchema(jsonContent.Schema);
}

private string ConvertToJsonSchema(OpenApiSchema schema)
{
    // Recursively build JSON Schema representation
    var builder = new StringBuilder();
    builder.Append("{");

    if (schema.Type != null)
    {
        builder.Append($"\"type\":\"{schema.Type}\"");
    }

    if (schema.Properties?.Count > 0)
    {
        builder.Append(",\"properties\":{");
        var props = schema.Properties
            .Select(p => $"\"{p.Key}\":{ConvertToJsonSchema(p.Value)}");
        builder.Append(string.Join(",", props));
        builder.Append("}");
    }

    if (schema.Items != null)
    {
        builder.Append(",\"items\":");
        builder.Append(ConvertToJsonSchema(schema.Items));
    }

    builder.Append("}");
    return builder.ToString();
}

Реальний- Світове використання

Наприклад: Petstore API

Дозвольте "'" пройти через класичну API Petstore .

Шаг 1: Завантаження спектру

POST /api/openapi/specs
Content-Type: application/json

{
  "name": "petstore",
  "source": "https://petstore3.swagger.io/api/v3/openapi.json",
  "basePath": "/petstore"
}

Відповідь:

{
  "name": "petstore",
  "basePath": "/petstore",
  "endpointCount": 19,
  "endpoints": [
    {"path": "/petstore/pet", "method": "POST"},
    {"path": "/petstore/pet/{petId}", "method": "GET"},
    {"path": "/petstore/pet/findByStatus", "method": "GET"},
    ...
  ],
  "success": true
}

Шаг 2: Використовуйте крапні кінцеві точки

Тепер всі кінцеві точки 19 доступні

### Get a pet by ID
GET /petstore/pet/123

### Response (auto-generated):
{
  "id": 123,
  "name": "Max",
  "category": {
    "id": 1,
    "name": "Dogs"
  },
  "photoUrls": [
    "https://example.com/max1.jpg"
  ],
  "tags": [
    {"id": 1, "name": "friendly"},
    {"id": 2, "name": "trained"}
  ],
  "status": "available"
}
### Find pets by status
GET /petstore/pet/findByStatus?status=available

### Response (auto-generated array):
[
  {
    "id": 42,
    "name": "Buddy",
    "status": "available",
    ...
  },
  {
    "id": 43,
    "name": "Luna",
    "status": "available",
    ...
  }
]

Шаг 3: Проверка спектру

GET /api/openapi/specs/petstore

### Shows full details:
### - All endpoints
### - Load time
### - Context configuration
### - Base path

Шаг 4: Перезавантаження, якщо змінюється спецификація

POST /api/openapi/specs/petstore/reload

Шаг 5: Remove When Done

DELETE /api/openapi/specs/petstore

Багато видів одночасно

Ви можете завантажити декілька зображень одночасно, кожна з них має власний базовий шляхM SK1

### Load Petstore at /petstore
POST /api/openapi/specs
{"name": "petstore", "source": "...", "basePath": "/petstore"}

### Load GitHub API at /github
POST /api/openapi/specs
{"name": "github", "source": "...", "basePath": "/github"}

### Load Stripe API at /stripe
POST /api/openapi/specs
{"name": "stripe", "source": "...", "basePath": "/stripe"}

### All three APIs now available simultaneously:
GET /petstore/pet/123
GET /github/users/octocat
GET /stripe/customers/cus_123

Спекти з контекстом

Для ще більшого реалізму

POST /api/openapi/specs
Content-Type: application/json

{
  "name": "petstore",
  "source": "https://petstore3.swagger.io/api/v3/openapi.json",
  "basePath": "/petstore",
  "contextName": "petstore-session"
}

Тепер усі кінцеві точки petstore мають однаковий контекст:

### Create a pet
POST /petstore/pet
{"name": "Max", "status": "available"}

### Response: {"id": 42, "name": "Max", "status": "available"}

### Get the pet (will reference same ID and name)
GET /petstore/pet/42

### Response: {"id": 42, "name": "Max", "status": "available"}
### Notice: Consistent ID and name from context

Випробовування кінцевої точки

Тестовий кінцевий пункт дозволяє спробувати кінцевий елемент без створення реального запиту:

POST /api/openapi/test
Content-Type: application/json

{
  "specName": "petstore",
  "path": "/pet/123",
  "method": "GET"
}

### Returns mock response without affecting routes

Це корисно для:

  • Перед переглядом відповідей перед інтеграцією
  • Випробовування конкретних кінцевих точок ізоляції
  • Проблеми з розладою схем

Менеджментний інтерфейс

Для візуального управління http://localhost:5116/OpenApi:

graph TD
    A[OpenAPI Manager UI] --> B[Load Spec Section]
    A --> C[Spec List]
    A --> D[Context Viewer]

    B --> E[URL Input]
    B --> F[JSON Input]
    B --> G[Context Configuration]

    C --> H[Spec Card]
    H --> I[Reload Button]
    H --> J[Delete Button]
    H --> K[View Endpoints]

    D --> L[Active Contexts]
    L --> M[Context Details]
    L --> N[Clear Context]

Особенности:

  • Перетягніть завантажити файл
  • Живе відкриття кінцевих точок - Подивіться на всі кінцеві точки одразу
  • Один-випробування - Випробувати будь-який кінцевий пункт кнопкою
  • Реальний-повідомлення про час - СигналR обновується, коли завантаження описів
  • Підвищення синтаксису - Красивий дисплей реагування JSON
  • Керування контекстом - Погляньте і зрозумійте контекст

Заawansовані характеристики

Параметри маршруту

Параметри маршруту автоматично виділяються:

# OpenAPI Spec
/pet/{petId}:
  get:
    parameters:
      - name: petId
        in: path
        schema:
          type: integer
GET /petstore/pet/123
### LLM receives: "Generate data for Pet with petId=123"
### Response: {"id": 123, ...}

Параметри запиту

Параметри питання впливають на відповідь:

/pet/findByStatus:
  get:
    parameters:
      - name: status
        in: query
        schema:
          type: string
          enum: [available, pending, sold]
GET /petstore/pet/findByStatus?status=available
### LLM receives: "Generate array of Pets with status=available"
### Response: [{"status": "available", ...}, ...]

Органи, які просять

POST/ PUT тіла включені в про prompt:

/pet:
  post:
    requestBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Pet'
POST /petstore/pet
Content-Type: application/json

{"name": "Max", "status": "available"}

### LLM receives: "Generate response for creating Pet with name=Max, status=available"
### Response: {"id": 42, "name": "Max", "status": "available"}

Описание та підсумки

описи OpenAPI скеровують LLM:

/pet/{petId}:
  get:
    summary: Find pet by ID
    description: Returns a single pet based on the ID provided

Вони входять у prompt, що допомагає LLM зрозуміти кінцевий пункт, ціль '

Коди статусу реагування

Система використовує перший успішний (2xxM SK1 реагування

responses:
  '200':
    description: Successful operation
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Pet'
  '404':
    description: Pet not found

Лише схема 200 є використана для створення макету. В даний момент не моделюються

СигналR Real-Aktualізації часу

Коли завантаження описів, інтерфейс отримує реальні-повідомлення про час через SignalR:

public async Task NotifySpecLoaded(string name, string basePath)
{
    await _hubContext.Clients.All.SendAsync("SpecLoaded", new
    {
        name,
        basePath,
        timestamp = DateTimeOffset.UtcNow
    });
}

public async Task NotifySpecDeleted(string name)
{
    await _hubContext.Clients.All.SendAsync("SpecDeleted", new
    {
        name,
        timestamp = DateTimeOffset.UtcNow
    });
}

Код інтерфейсу JavaScript:

const connection = new signalR.HubConnectionBuilder()
    .withUrl('/hubs/openapi')
    .build();

connection.on('SpecLoaded', (data) => {
    showNotification(`Spec "${data.name}" loaded at ${data.basePath}`, 'success');
    refreshSpecList();
});

connection.on('SpecDeleted', (data) => {
    showNotification(`Spec "${data.name}" deleted`, 'info');
    refreshSpecList();
});

Поддержка формату

Система підтримує:

  • OpenAPI 3.0.x
  • OpenAPI 3.1.x
  • Swagger 2.0
  • Формат JSON
  • Формат YAML

Як JSON, так і YAML спектри автоматично розпізнаються та аналізуються.

Найкращі практики

1. Використовуйте описові назви спектру

 Bad:  {"name": "spec1", ...}
 Good: {"name": "github-v3", ...}

2. Установити необхідні базові шляхи

Уникніть конфліктів, використовуючи унікальні базові шляхи:

### Good separation
/petstore/...
/github/...
/stripe/...

### Bad (conflicts!)
/api/... (multiple specs)

3. Перезавантаження, коли змінюються характеристики

Якщо ваша спецификація OpenAPI зaktualizована, перезавантаження їїM SK1

POST /api/openapi/specs/my-api/reload

4. Використовуйте контекст для зв 'язків

POST /api/openapi/specs
{
  "name": "petstore",
  "source": "...",
  "contextName": "test-session"
}

### Now all petstore calls maintain consistency

5. Чисти після тестування

Remove specs you're no longer using

DELETE /api/openapi/specs/old-spec

Ограничення

  1. Коди статусу реагування - Скоріш за все, успішні відповіді
  2. Аuthentication - Заголовки Auth приймаються, але не підтверджують
  3. Випробовування - Прохання до перевірки на основі skeмів не застосовується
  4. Статус - Немає реальної бази данихM SK1 дані генеруються поновленням щоразу
  5. Результати - генерація LLM додає затримки ~100-500ms на żądaння

Інтеграція з Regular Mock Endpoints

Спекти OpenAPI працюють поряд з звичайними /api/mock кінцеві точки:

### OpenAPI-based (from spec)
GET /petstore/pet/123
### Uses Pet schema from OpenAPI spec

### Regular mock (shape-based)
GET /api/mock/custom?shape={"id":0,"name":"string"}
### Uses explicit shape parameter

Обидві системи використовують один і той самий базовий LLM, але вони відрізняються в тому, як представлена схема.

Оптимізація ефективності

Камера

Завантаження описів зберігаються в пам 'яті:

private readonly ConcurrentDictionary<string, OpenApiSpecConfig> _specs = new();

Тривалість служби

DynamicOpenApiManager є одинтонним, так що характеристики залишаться завантажені протягом тривалості використанняM SK1

Паралельно розрахунки завантаження

Множество описів можна завантажити паралельно:

### Send these simultaneously
POST /api/openapi/specs {"name": "spec1", ...}
POST /api/openapi/specs {"name": "spec2", ...}
POST /api/openapi/specs {"name": "spec3", ...}

Усі три будуть завантажуватись паралельно, не послідовноM SK1

Подолання проблем

Шпек Won't Завантаження

Проблема: Нездатність завантаження опису

Рішення:

  • Проверьте доступність URL
  • Перевірити, чи є файл ( для локальних шляхівM SK1
  • Упевниться, що JSON/YAML важливий
  • Подивіться на проблеми з CORS (для віддалених URLs)

Не було виявлено кінцевого пункту

Проблема: 404 на очікуваному кінцевому етапі

Рішення:

  • Перевірити базовий шлях: /petstore + /pet/123 = /petstore/pet/123
  • Подивіться, чи спецификація насправді визначає цей шлях
  • Упевниться, що HTTP-metodа підходить (GET vs POST)

Відповідь не співпадає з схемою

Проблема: Згенеровані дані не співпадають з очікуваною схемою

Рішення:

  • Проверьте, чи схема у спецификації правильна
  • Ви перевіряєте, що: ' ви дивитесь на правильну відповідь МSK1 проти 201)
  • Пам 'ятайте: генерація LLM є можливим , не детермінативним

Завершення

Динамічний генератор макетів OpenAPI перетворює будь-яку спецификацію OpenAPI на повністю функціональну макетову API за кілька секунд.

Просто завантаження опису і почати робити запити. LLM генерує реалістичні , різні дані, які відповідають вашим схемам МSK2 роблячи їх ідеальними для

  • Розробка інтерфейсу в той час, як задній бік будується
  • Тестування інтеграції без використання реального API
  • Оффлайн розвиток коли зв 'язок обмежений
  • Завантаження тестування без проблем з квотами
  • Прототипування нові характеристики швидко

Поєднано з контекстами API, ви отримуєте statesful mock APIs, які зберігають послідовність по всіх дзвінкахM SK1 zapewniając ще більш реальну симуляцію виробничих систем.

Майбутнє макетних API є динамічними, розумними, і керованими тими самими LLM, які дають живлення сучасним інструментам розробкиM SK2 Добро пожаловать в нову епоху макетування API

logo

© 2026 Scott Galloway — Unlicense — All content and source code on this site is free to use, copy, modify, and sell.