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
LLMApi: OpenAPI Генератор динамічного мока : Завантаження будь-якого спектру МSK2 Мок будь-який API
Wednesday, 05 November 2025
NOTA: Ця стаття, в основному, створена штучною inteligenцією як частина мого пакету неджетів, як релізова документація.
Введение
Чи ви коли-небудь хотіли протестувати API, яке ще не було розроблено?' не підготовано до тесту? ? Чи ви хотіли розробити бездротовий тест, не заважаючи обмеженням швидкості? МSK2 Генератор динамічного макка OpenAPI дозволяє завантажити будь-яку спецификацію OpenAPI і миттєво створювати повністю?МSK3функціональний макк API з реалістичними даними?
Ніяких файлів конфігурації. Ніхто не створив ручних кінцевих точок
Ви можете знайти Тут GitHub для проекту, всі громадські домени і т.д.

Проблема: Розробка блоків 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 , і вона автоматично :
- Розшифровує спецификацію
- Відкриє всі кінцеві точки
- генерує реальні моделі даних, використовуючи LLM
- Використовує модель 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]
Ключові компоненти:
- Динамічний OpenApiManager - Manages loaded specs and route matching
- OpenApiSpecLoader - Переносить та аналізує документи OpenAPI
- OpenApiRequestHandler - генерує відповіді для відповідних кінцевих точок
- Промпт-будівник - Створює LLM прохання з схемами OpenAPI
- 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
Ограничення
- Коди статусу реагування - Скоріш за все, успішні відповіді
- Аuthentication - Заголовки Auth приймаються, але не підтверджують
- Випробовування - Прохання до перевірки на основі skeмів не застосовується
- Статус - Немає реальної бази данихM SK1 дані генеруються поновленням щоразу
- Результати - генерація 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