api-contract-checker

name	api_contract_checker
description	Check Swagger/OpenAPI contracts or openapi_api_analyzer interface lists for missing API contract details, then generate developer-facing confirmation questions for API automation readiness.

API Contract Checker

Use this skill after openapi_api_analyzer or directly on an OpenAPI/Swagger file when the user needs to find contract gaps before writing API automation cases.

Goal

This skill checks whether an API contract is complete enough for stable automated testing. It does not call real APIs, create accounts, generate tokens, or execute high-risk operations.

Inputs

Supported inputs:

• openapi.json
• openapi.yaml / openapi.yml
• api_interface_list.csv generated by openapi_api_analyzer
• api_interface_list.xlsx generated by openapi_api_analyzer when openpyxl is installed

Recommended pipeline:

python3 skills/openapi_api_analyzer/scripts/parse_openapi.py openapi.yaml --output-dir output/interfaces
python3 skills/api_contract_checker/scripts/check_contract.py --input output/interfaces/api_interface_list.csv --output-dir output/contract

Direct OpenAPI check:

python3 skills/api_contract_checker/scripts/check_contract.py --input openapi.yaml --output-dir output/contract

Diff-only check for V6 incremental review:

python3 skills/api_contract_checker/scripts/check_contract.py \
  --base openapi.base.yaml \
  --input openapi.current.yaml \
  --output-dir output/contract-diff

Diff-only check from openapi_api_analyzer outputs:

python3 skills/api_contract_checker/scripts/check_contract.py \
  --base output/base/api_interface_list.csv \
  --input output/current/api_interface_list.csv \
  --output-dir output/contract-diff

Outputs

The script writes:

• dev_contract_questions.md: developer-facing TODO list grouped as questions.
• contract_check_report.json: full issue list.
• contract_check_summary.json: counts by severity, issue type, and module.
• contract_check_report.md: table version of the issue list.
• contract_check_report.csv: spreadsheet-friendly issue list.
• api_change_diff.json and api_change_diff.md: written only when --base is provided.

Check Rules

Rules are configured in rules/contract_rules.yaml. The default checks cover:

• Empty requestBody DTO.
• Empty response DTO.
• Missing summary.
• Missing operationId is not treated as a blocker; when absent, tools generate a stable fallback from method + path, such as authLoginPasswordPost.
• Only success responses are documented, with no error responses.
• Sensitive endpoints without bearer authentication.
• Password endpoints with unclear encryption rules.
• Captcha or verification-code endpoints without a test-environment strategy.
• Third-party login endpoints without mock code / token strategy.
• Token/session endpoints without lifetime and invalidation rules.
• Delete, deactivate, account deletion, and account cancellation endpoints without execution strategy.
• Parameters or fields with missing type, description, or required semantics when visible from the OpenAPI schema.

V6 Diff Mode

When --base is provided, the checker compares the baseline and current input, then only runs contract checks for:

• added: new method + path interfaces.
• changed: existing method + path interfaces whose operation contract changed.

removed interfaces are written to api_change_diff.json / api_change_diff.md for traceability, but they are not checked for contract gaps because they do not exist in the current API surface.

For OpenAPI input, the diff compares each operation after expanding local $ref schemas, so DTO field changes are treated as operation changes. It also includes path-level parameters, effective security, and security schemes in the comparison.

For api_interface_list.csv / .xlsx input, the diff compares rows keyed by method + path. Changed rows are checked using the current row values.

Issue Fields

Each issue contains:

• issueId
• severity: High, Medium, or Low
• module
• method
• path
• summary
• issueType
• issueDesc
• impact
• questionToDev
• suggestion
• status: defaults to 待确认

Severity Guide

• High: blocks stable automation or touches security/high-risk flows, such as empty login DTOs, token rules, password encryption, captcha strategy, and account deletion strategy.
• Medium: causes weak assertions or unstable negative cases, such as missing error responses, third-party login mock strategy, incomplete parameter descriptions, and generic delete-risk handling.
• Low: affects readability or naming, such as missing summary.

How It Connects To openapi_api_analyzer

openapi_api_analyzer produces the interface inventory and coarse contract TODOs. api_contract_checker consumes either the original OpenAPI file or api_interface_list.csv and expands the findings into structured developer questions.

openapi.json / openapi.yaml
  -> openapi_api_analyzer
  -> api_interface_list.csv
  -> api_contract_checker
  -> dev_contract_questions.md

Use the CSV path when you want the checker to preserve the module, priority, auth flag, DTO labels, and contract issues already extracted by openapi_api_analyzer.

For incremental review, run openapi_api_analyzer for both baseline and current OpenAPI documents, then pass the two generated CSV files to api_contract_checker --base ... --input ....

Next Skill

After contract issues are confirmed or accepted as disabled drafts, use yaml_case_generator to create YAML API test case drafts:

python3 skills/yaml_case_generator/scripts/generate_yaml_cases.py \
  --openapi openapi.yaml \
  --contract confirmed_contract.yaml \
  --output cases/api_cases.yaml

For incremental case generation, pass the V6 diff output:

python3 skills/yaml_case_generator/scripts/generate_yaml_cases.py \
  --openapi openapi.current.yaml \
  --contract confirmed_contract.yaml \
  --diff output/contract-diff/api_change_diff.json \
  --output cases/changed_cases.yaml

Dependencies

Required:

python3 -m pip install pyyaml

Optional for reading .xlsx input:

python3 -m pip install openpyxl