Web и API

Разобрать OpenAPI-спецификацию

Показывает серверы, пути и операции OpenAPI, а также пропущенные описания.

Python Windows macOS Linux Продвинутый
Скачать openapi_inspect.py
Описание

Что делает скрипт

Скрипт читает OpenAPI-файл в JSON или YAML, проверяет версию и перечисляет операции по путям. Он отмечает методы без operationId, summary и описание, а также показывает схемы безопасности и deprecated-операции. По флагу --json сохраняется машинный отчёт.

Запуск

Быстрый старт

python openapi_inspect.py --spec openapi.yaml

Скачайте файл, откройте терминал в папке со скриптом и выполните команду. В Linux и macOS интерпретатор может называться python3, в Windows - python или py.

Примеры

Другие варианты

  • python openapi_inspect.py --spec openapi.json --json report.json
  • python openapi_inspect.py --spec https://example.com/openapi.json
Зависимости

Что понадобится

Python 3.10+ Интерпретатор Python
Windows winget install Python.Python.3.12
macOS brew install python
Linux sudo apt install python3
Python-пакет PyYAML Чтение OpenAPI в YAML
Windows py -m pip install PyYAML
macOS python3 -m pip install PyYAML
Linux python3 -m pip install PyYAML
Исходник

openapi_inspect.py

#!/usr/bin/env python3
"""Краткий разбор OpenAPI-спецификации."""
from __future__ import annotations

import argparse
import json
from pathlib import Path
from urllib.request import urlopen

import yaml

METHODS = ("get", "post", "put", "patch", "delete", "head", "options", "trace")


def load_spec(source: str) -> dict:
    if source.startswith("http://") or source.startswith("https://"):
        with urlopen(source, timeout=15) as response:
            text = response.read(5_000_000).decode("utf-8")
        if source.lower().endswith((".yaml", ".yml")):
            data = yaml.safe_load(text)
        else:
            data = json.loads(text)
    else:
        path = Path(source)
        if not path.is_file():
            raise SystemExit(f"Файл не найден: {path}")
        text = path.read_text(encoding="utf-8")
        data = yaml.safe_load(text) if path.suffix.lower() in {".yaml", ".yml"} else json.loads(text)
    if not isinstance(data, dict):
        raise SystemExit("Спецификация должна быть объектом")
    return data


def main() -> int:
    parser = argparse.ArgumentParser(description="Разобрать OpenAPI")
    parser.add_argument("--spec", required=True, help="Путь или URL к JSON/YAML")
    parser.add_argument("--json", type=Path, help="Сохранить отчёт")
    args = parser.parse_args()

    spec = load_spec(args.spec)
    version = spec.get("openapi") or spec.get("swagger") or "не указана"
    info = spec.get("info") or {}
    servers = spec.get("servers") or []
    paths = spec.get("paths") or {}
    if not isinstance(paths, dict):
        raise SystemExit("Поле paths должно быть объектом")

    print(f"Версия: {version}")
    print(f"Название: {info.get('title', 'без названия')}")
    print(f"Версия API: {info.get('version', 'не указана')}")
    if servers:
        print("Серверы:")
        for server in servers:
            print(f"  {server.get('url', '?')} {server.get('description', '')}".rstrip())

    report = {"version": version, "title": info.get("title"), "servers": servers, "operations": [], "issues": []}
    for path, item in paths.items():
        if not isinstance(item, dict):
            continue
        for method in METHODS:
            operation = item.get(method)
            if not isinstance(operation, dict):
                continue
            entry = {
                "method": method.upper(),
                "path": path,
                "operationId": operation.get("operationId"),
                "summary": operation.get("summary"),
                "deprecated": bool(operation.get("deprecated")),
                "tags": operation.get("tags") or [],
            }
            report["operations"].append(entry)
            missing = [name for name in ("operationId", "summary") if not operation.get(name)]
            if missing:
                report["issues"].append({"method": method.upper(), "path": path, "missing": missing})
            print(f"{method.upper():<7} {path}  {operation.get('summary', '')}".rstrip())

    components = spec.get("components") or {}
    security = components.get("securitySchemes") or {}
    if security:
        print("Схемы безопасности:")
        for name, scheme in security.items():
            print(f"  {name}: {scheme.get('type', '?')} {scheme.get('scheme', '')}".rstrip())

    print(f"Операций: {len(report['operations'])}, замечаний: {len(report['issues'])}")
    if args.json:
        args.json.write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
        print(f"Отчёт: {args.json}")
    return 0 if not report["issues"] else 1


if __name__ == "__main__":
    raise SystemExit(main())

Скрипты работают с файлами и настройками системы. Перед запуском прочитайте код и проверьте пути. Особенно если скрипт удаляет, перезаписывает или перемещает данные.

CLI 1.0.0

Скачать без браузера

Команда скачает этот файл в текущую папку. CLI работает на Windows, macOS и Linux.

scriptdock get web-openapi-inspect
  • Поиск по всему каталогу
  • Python 3.10+
  • Без внешних пакетов
Скачать CLI

GUI-версия готовится. Подробнее

Категория

Web и API

HTTP, API, сайты, заголовки, SSL и проверка веб-сервисов.