openapi-api-analyzer

name	openapi_api_analyzer
description	Parse Swagger/OpenAPI JSON or YAML files and generate API interface inventories, automation priority suggestions, and contract review TODOs for API automation planning.

OpenAPI API Analyzer

Use this skill when the user provides or references a Swagger/OpenAPI contract and wants an interface inventory, API automation scope, DTO overview, authentication notes, or contract gaps.

Inputs

• openapi.json, openapi.yaml, or openapi.yml
• Supports OpenAPI 3.x and Swagger 2.0 documents.
• The parser accepts JSON because JSON is valid YAML.

Outputs

The bundled script writes these files to the selected output directory:

• api_interface_list.xlsx
• api_interface_list.csv
• api_interface_list.md
• api_contract_todo.md

Parsing Rules

For each operation under paths, extract:

• Module tag: first operation tag; fallback to path-level tag; fallback to 未分组.
• summary: operation summary; fallback to description.
• HTTP method and path.
• operationId; if missing, generate one from method + path, such as authLoginPasswordPost.
• Bearer auth requirement:
  • OpenAPI 3.x: detects components.securitySchemes entries using HTTP bearer, bearer format, or Authorization apiKey header.
  • Swagger 2.0: detects securityDefinitions entries using oauth2 or Authorization apiKey header.
  • Operation-level security: [] means no auth.
  • Operation-level security overrides global security; otherwise global security is used.
  • Explicit Authorization header parameters are treated as auth-related.
• Parameters grouped by path, query, and header.
• Request DTO:
  • OpenAPI 3.x: requestBody.content schemas, preferring JSON media types.
  • Swagger 2.0: body parameter schema.
• Response DTO:
  • response schemas from JSON-like media types; includes status code mapping.
• Response status codes.
• Automation priority suggestion:
  • P0 for auth/session/account/payment/order/security-critical endpoints.
  • P1 for mutating business APIs (POST, PUT, PATCH, DELETE) or endpoints with request DTOs.
  • P2 for read-only/list/detail APIs.
• Contract issues and TODOs:
  • Empty or object-without-properties request/response DTOs.
  • Captcha or verification-code endpoints.
  • Password endpoints.
  • Third-party login endpoints.
  • Account注销/注销账号/delete-account endpoints.
  • Missing summary.
  • Missing response definitions.

Usage

From the skill directory or repository root:

python3 skills/openapi_api_analyzer/scripts/parse_openapi.py openapi.yaml

Write outputs to a custom directory:

python3 skills/openapi_api_analyzer/scripts/parse_openapi.py ./openapi.json --output-dir ./reports

If dependencies are missing:

python3 -m pip install pyyaml openpyxl

Expected Workflow

1. Locate the OpenAPI/Swagger source file.
2. Run scripts/parse_openapi.py.
3. Review api_interface_list.xlsx for automation planning.
4. Review api_contract_todo.md before writing tests, especially items related to empty DTOs, captcha flows, password changes, third-party login, and account deletion.

Next Skill

For a developer-facing contract question list, pass the generated CSV to api_contract_checker:

python3 skills/api_contract_checker/scripts/check_contract.py --input ./reports/api_interface_list.csv --output-dir ./reports/contract