Yapi Skill

Yapi Search and Query Skill

Overview

You can directly use Python scripts to call the Yapi API, search for Yapi interfaces to locate the interfaceId, or get detailed information of a specific interface (request parameters, response body, description in Markdown). Prefer using this skill instead of starting the yapi-mcp-server (Java/Docker).

Beyond reading, this skill can also write: sync (upsert) a single interface's docs into YApi from a YApi-native payload — typically converted from an OpenAPI contract. Writing is read-modify-write (only managed fields are overwritten; existing writable fields are re-sent to best-preserve un-managed content like mock / test cases / status — verified end-to-end: up is merge semantics, fields not sent are preserved), dry-run by default (a preview artifact is written to a file; only a compact summary is printed), and never deletes (YApi's OpenAPI has no delete endpoint).

Core principle: Configure environment -> choose search / query / sync as needed -> for sync, convert to a payload, dry-run to preview, then apply.

Announce at start: "I am using the yapi-skill to search/query or sync Yapi interface details."

Prerequisites

This skill depends on a local configuration file (base_url + projectId -> token). If you haven't initialized it, don't know how to get the token, or need to switch between multiple environments, please read first:

• skills/yapi-skill/references/initialization.md

Configuration paths support the following override methods:

• Environment variable: YAPI_SKILL_CONFIG=/path/to/config.json
• Single command execution: --config /path/to/config.json (takes effect for searchInterfaces.py / getInterfaceDetail.py)

For Windows users, if the python3 command is not available, try using py -3 or python.

Workflow

Step 1: Decide the Target (Search or Query Details)

Determine whether you need to first find a specific interface (using the search function) or if you already have the specific interface ID or URL to query the detailed information.

Step 2: Execute the Query

Scenario A: Get Interface Details Directly (Recommended)

Use this when you already know the specific interface URL or the projectId and interfaceId.

python3 skills/yapi-skill/scripts/getInterfaceDetail.py \
  --url 'http://yapi.example.com/project/1650/interface/api/414469' \
  --format markdown

Description:

• --url supports directly pasting the interface page URL (the script will automatically parse projectId/interfaceId).
• --format supports json (for secondary processing) and markdown (for readability).
• It also supports --projectId + --interfaceId (when you already have the IDs).

Security warning: The Markdown output may contain example request headers/example values from the interface definition (e.g., Authorization example). Please sanitize it yourself before sharing it externally.

Scenario B: Search for Interfaces (Locate interfaceId)

Use this when you only know the interface keyword or path.

python3 skills/yapi-skill/scripts/searchInterfaces.py --keyword login --format markdown

Common parameters:

• By default, it searches all projects in the project_tokens of the configuration file. (Use --projectName to narrow the scope).
• --projectName: Fuzzy filter by project name (Optional).
• --keyword: Fuzzy search by interface title (Optional).
• --path: Fuzzy search by interface path (Optional).
• --format json|markdown: Defaults to json.
• --config <path>: Specify the configuration file path (Overrides default path, Optional).

Write / Sync Workflow

Use this to push an interface's docs into YApi from a contract (e.g. OpenAPI). The scripts are source-agnostic primitives; deciding which interfaces to sync is your job.

Safety rules (always):

• Only touch interfaces you explicitly target — one interface per upsertInterface.py call. Never enumerate-and-sync a whole spec blindly.
• Dry-run first (the default). Read the field-level diff from the preview artifact, show it to the user, get confirmation, then re-run with --apply.
• Creates/updates only — YApi's OpenAPI cannot delete. up is read-modify-write and re-sends existing writable fields to best-preserve un-managed content (mock, test cases, status — verified end-to-end: up merges, so fields not sent are preserved); remove stale interfaces manually in the YApi UI.