Автоматическая генерация документации — это использование AI для создания описаний функций, классов, модулей и целых проектов на основе исходного кода. Современные LLM (Claude, GPT-4o) отлично понимают код и способны генерировать качественные docstrings, README-файлы и API-справочники. Через ModelSwitch API вы можете подключить эту возможность в свой CI/CD-пайплайн.
Генерация docstrings для функций
Самый частый use case — автоматическое добавление документации к функциям. Claude 3.5 Sonnet особенно хорош для задач, связанных с кодом:
from openai import OpenAI
client = OpenAI(
base_url="https://api.modelswitch.ru/v1",
api_key="msk_ваш_ключ"
)
def generate_docstring(code: str) -> str:
response = client.chat.completions.create(
model="claude-3.5-sonnet", # Лучшая модель для работы с кодом
messages=[
{"role": "system", "content": (
"Ты — технический писатель. Сгенерируй docstring в формате Google Style "
"для данной функции. Верни ТОЛЬКО docstring, без кода функции."
)},
{"role": "user", "content": code}
],
temperature=0.2
)
return response.choices[0].message.content
# Пример использования
code = '''
def calculate_shipping(weight, distance, express=False):
base_rate = 5.0
per_kg = 0.5
per_km = 0.01
cost = base_rate + weight * per_kg + distance * per_km
if express:
cost *= 2.5
return round(cost, 2)
'''
print(generate_docstring(code))
# Результат:
# """Calculate shipping cost based on weight and distance.
#
# Args:
# weight: Package weight in kilograms.
# distance: Delivery distance in kilometers.
# express: Whether to use express delivery (2.5x cost).
#
# Returns:
# Calculated shipping cost rounded to 2 decimal places.
# """Генерация README для проекта
AI может проанализировать структуру проекта и создать информативный README:
import os
def collect_project_structure(path: str, max_depth: int = 3) -> str:
result = []
for root, dirs, files in os.walk(path):
depth = root.replace(path, "").count(os.sep)
if depth >= max_depth:
continue
indent = " " * depth
result.append(f"{indent}{os.path.basename(root)}/")
for f in files[:10]: # Ограничиваем количество файлов
result.append(f"{indent} {f}")
return "
".join(result)
structure = collect_project_structure("./my-project")
response = client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": (
"Сгенерируй README.md для проекта. Включи: описание, "
"установку, запуск, структуру проекта, лицензию. Формат Markdown."
)},
{"role": "user", "content": f"Структура проекта:
{structure}"}
],
temperature=0.4
)Генерация API-справочника
Для REST API можно автоматически генерировать документацию на основе кода эндпоинтов:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.modelswitch.ru/v1",
apiKey: "msk_ваш_ключ",
});
async function generateApiDocs(controllerCode: string): Promise<string> {
const response = await client.chat.completions.create({
model: "claude-3.5-sonnet",
messages: [
{
role: "system",
content:
"Проанализируй код контроллера и сгенерируй API-документацию " +
"в формате OpenAPI 3.0 YAML. Включи пути, параметры, схемы ответов.",
},
{ role: "user", content: controllerCode },
],
temperature: 0.1,
});
return response.choices[0].message.content ?? "";
}Интеграция в CI/CD
Автогенерацию документации удобно встроить в CI/CD. Пример GitHub Actions workflow:
name: Generate Docs
on:
push:
branches: [main]
paths: ["src/**/*.py"]
jobs:
docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Generate documentation
env:
MODELSWITCH_API_KEY: ${{ secrets.MODELSWITCH_API_KEY }}
run: python scripts/generate_docs.py
- name: Commit docs
run: |
git add docs/
git commit -m "docs: auto-generate API documentation" || true
git pushЧерез ModelSwitch вы получаете доступ к лучшим моделям для кодогенерации — Claude для анализа кода, GPT-4o для генерации текста — и всё через единый API-ключ. Стоимость генерации документации для среднего проекта (50 файлов) составляет менее $1.