SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsapifox-import-export

apifox-import-export

Deployment & operations

View repository

Updated 10-15 12:09

About this skill

Import/Export and Quality Gates

Prerequisites: first read ../apifox-cli/SKILL.md. If the old master entry conflicts with this skill's domain rules, the current CLI help and this skill take precedence.

Specific command parameters are subject to the current CLI help. Before import, focus on checking the file format, OpenAPI quality gates, route skeleton risk, tags grouping, native format module strategy, ignoreCount, and whether a clean project is needed for validation. After import, the Agent must confirm results based on agentHints, list/get, and necessary run/report, and must not judge completion solely by the import command returning success.

When to Use

  • Generate API spec from a codebase, PRD, requirements document, test document, or discussion records and import it into Apifox.
  • Import project data such as OpenAPI, Postman, HAR, and Apifox native formats.
  • Configure automatic import.
  • Export OpenAPI, Markdown, HTML, Postman, or Apifox native formats.
  • Need to determine whether the generated spec is merely a "route skeleton".
  • Migrate, back up, or copy an Apifox project, especially when module reuse or creation needs to be controlled.

When Not to Use

  • Import/copy existing endpoint, test-case, or test-scenario step into a test scenario: switch to apifox-test-scenario, use test-scenario import-steps or test-scenario add-ref。
  • Finely maintain test scenario steps, variables, assertions, or processors: switch to apifox-test-scenario。

Command Entry Points

Use the current CLI help to query the parameters of import、import auto-import、export and export settings . Do not skip the quality gates below before import.

Core Principles

  1. Prioritize checking for an existing generator in the project; do not first hand-write an extraction script.
  2. Do not mistake "complete paths" for "complete API spec".
  3. Quality metrics must be output before import.
  4. Completeness and readability must be accepted at the same time.
  5. When the import strategy is uncertain, prioritize creating a temporary/corrected project for validation; do not pollute an existing project.
  6. A large number of ignoreCount in the import result is a risk signal, not an ordinary success.
  7. Apifox directory grouping depends on OpenAPI operation tags.
  8. Do not assume the file extension represents the actual format.

Standard Workflow

Step 0. Clarify the Task Type

First determine which type of task the user wants to do:

Task Next Step
Generate spec from a codebase, PRD, or document and import it Continue to Step 1
Directly import an existing file Start from Step 3
Configure automatic import First read the current CLI help and schema, then create the configuration
Export documents or OpenAPI Directly use the export command, and after export check whether the file was generated
Migrate or back up an Apifox project Use Apifox native format to export and import, and confirm the module import strategy
Import existing resources into a test scenario Switch to apifox-test-scenario, do not go through OpenAPI import

If the user has not specified the target project, team, import strategy, or whether creating new projects is allowed, first determine based on context; when uncertain, ask only one minimal necessary question.

Step 1. Search for an existing generator in the project

When encountering a requirement to "generate API spec / documentation / types from source code / documentation / PRD / test documentation / discussion," first search whether the project already has:

openapi
swagger
routegen
route-gen
docs generator
api docs
schema generator
cmd/openapi
cmd/*openapi*

Correct direction:

  • First run the project's built-in generator.
  • Prioritize tools that can extract handler request/response structs, DTOs, and schemas.
  • Do not first hand-write a script to extract paths from router files, otherwise it is very easy to end up with only a method + path skeleton.

If no generator can be found, then consider generating the spec from framework routes, comments, DTOs, schemas, tests, or documentation; after generation, the quality gates from Step 3 onward must still be followed.

Step 2. Generate the spec and confirm the file format

  • Run the project's built-in generator or the official generation command.
  • Keep the original artifact; do not directly overwrite the user's existing files.
  • Do not determine the format based on the file extension.
  • Before reading the generated file, first look at the beginning of the file or use a parser that supports JSON/YAML.
  • The generator may output YAML to a .json file; if it is actually YAML, it should be renamed to .yaml or parsed as YAML.

Step 3. Collect pre-import quality metrics

Before import, the generated OpenAPI file must actually be parsed, and real statistics must be reported. Do not use example values, default values, or placeholder values.

Must collect statistics on:

Metric Meaning Purpose
paths Number of OpenAPI paths Determine the API scale
operations Actual number of operations Determine the import scale
schemas components.schemas count Determine model completeness
writes Number of write APIs such as POST/PUT/PATCH Determine the body coverage target
withBody Number of write APIs with requestBody Determine requestBody coverage
emptyObjectBodies Number of requestBody schemas that are empty objects Determine whether it is a route skeleton

When outputting, you must write the "actual statistical results"; for example, a table or JSON is acceptable, but each value must come from the parsing result of the current file.

Step 4. Determine spec completeness

  • Do not judge quality by a fixed number of schemas.
  • Small-scale, pure GET, health check, webhook pass-through, and projects without JSON bodies,schemas=0/1 can be acceptable.
  • For large projects, if there are many APIs and many write APIs, but very few schemas, treat it as a suspected route skeleton spec.
  • A large number of POST/PUT/PATCH requests missing bodies or having empty {}, is a strong risk signal.
  • Only method + path cannot prove that requestBody, response, and schema are complete.

Risk assessment:

Phenomenon Assessment Handling
Large API scale and many write APIs, but very few schemas Suspected route skeleton spec Continue checking DTOs, handler request/response structs, in-project generators, or documentation sources
Many write APIs, but withBody coverage is clearly insufficient requestBody incomplete Continue to supplement the request DTO or switch the generator
There are many emptyObjectBodies High risk, may just be an empty shell body Do not import as the final spec
Small, pure GET, health check, webhook passthrough Very few schemas may be reasonable Judge based on the business form, do not force failure

If it is determined to be a routing skeleton spec, do not import it as the final version; at most import a temporary project for exploration.

Step 5. Validate tags and document readability

An API spec must not only have complete models, but also be readable, navigable, and reasonably grouped in Apifox.

Must check:

  • Whether operations have business-oriented tags。
  • Whether tags are grouped by business domain, rather than mechanically grouped by URL path.
  • Whether schemas are fully preserved.
  • Whether operationId, summary, and description are readable.

Recommended tags form:

paths:
  /api/v1/<resource>:
    post:
      tags:
        - <业务域名称>

Not recommended: after import, the directory is mechanically expanded by technical path, for example:

api / v1 / <resource>

It is more recommended to set tags by product module, business domain, resource domain, or user-understandable functional domain, so that the directory in the Apifox client serves business navigation, rather than serving code path restoration.

If the tags in the generator output are obviously too coarse or mechanically derived from technical paths, for example a large number of endpoints fall under api、v1、rest、service、controller and other directories, you must stop before import and first ask the user whether they allow generating a corrected spec with more reasonable tags and cleaner project documentation. Before the user agrees, do not import that spec as the final project.

Step 6. Choose the import project

  • When the import strategy is uncertain, prioritize creating a temporary/corrected project for verification.
  • Do not repeatedly import a new spec and pollute an existing project.
  • If a skeleton spec has already been imported into an existing project, importing a complete spec again may result in old endpoints being ignored, new endpoints being appended, and the project becoming mixed.
  • Temporary project naming should preferably express the version and purpose, for example API - Full Spec、API - Grouped Full Spec。

Step 7. Execute the import and check the results

After import, do not only look at whether the command succeeded; also look at the result counts.

If in the import results ignoreCount is obviously high, you must not treat "command executed successfully" as "import quality qualified." You must continue to determine:

  • Whether it was imported into an existing project.
  • Whether the endpoint matching strategy does not meet expectations.
  • Whether the old spec and the new spec are mixed.
  • Whether it should be re-imported into a clean project instead.

Step 7A. Apifox native format import strategy

Apifox native format is suitable for project migration, backup, cross-project copying, and local resource relocation. Common commands:

apifox import --project <projectId> --format apifox --file ./project.apifox.json

The default module strategy is match-name: when the source module name uniquely matches a module name in the target project, import into the existing module; when there is no match, create a new module. When importing the same project a second time, prefer the default strategy to avoid creating duplicate modules with the same name.

apifox import --project <projectId> --format apifox --file ./project.apifox.json --module-import-mode match-name

If the test goal is to copy a completely new set of modules each time, use new：

apifox import --project <projectId> --format apifox --file ./project.apifox.json --module-import-mode new

When the target project has multiple modules with the same name, or when you need precise control over where source modules go, use --module-map. It can be passed repeatedly, and its priority is higher than --module-import-mode：

apifox import --project <projectId> --format apifox --file ./project.apifox.json \
  --module-map "商店 API=8049476" \
  --module-map "管理 API=8049482"

Common mapping syntax:

Syntax Purpose
"源模块名=目标模块ID" Import into a specified existing module
"source:源模块ID=目标模块ID" When the source module name is duplicated, use the source module ID to specify it precisely
"源模块名=default" Import into the target project's default module
"源模块名=new" Only create new modules for that source module

Specifying only some source modules is also fine; unspecified source modules continue to be handled according to --module-import-mode . For target modules, it is recommended to use module IDs to avoid ambiguity with modules of the same name in the target project.

After import, you must verify:

  • Whether the module count matches expectations; a second import should not unintentionally add modules with the same name.
  • Whether the resource counts for APIs, Schemas, test cases, test scenarios, WebSocket, Socket.IO, etc. match the import results.
  • Whether the single-endpoint test case categories are visible.
  • If test suites are imported, spot-check whether the scenario and case references in the suites point to resources in the new project.

Step 7B. Apifox native format export strategy

Full backup or migration:

apifox export --project <projectId> --format apifox --output ./project.apifox.json

Export only specified endpoints or directories, suitable for partial migration or minimal reproduction:

apifox export --project <projectId> --format apifox --scope apis --api-ids 1001,1002 --output ./selected.apifox.json
apifox export --project <projectId> --format apifox --scope folders --folder-ids 2001 --output ./folder.apifox.json

Export by tag, suitable for delivery by business domain:

apifox export --project <projectId> --format apifox --scope tags --include-tags pet,store --exclude-tags deprecated --output ./tagged.apifox.json

By default, API debugging and single-endpoint cases are included; if you only need endpoint definitions, explicitly disable it:

apifox export --project <projectId> --format apifox --no-include-api-cases --output ./apis-only.apifox.json

After export, check that the file exists and the size is reasonable, and perform an import verification in a temporary project, especially before sending it to others or using it for migration.

Step 8. Read back, verify, and report

  • Read back the endpoint list and confirm that the total number of endpoints matches the import results.
  • Spot-check at least one read endpoint and one write endpoint; for write endpoints, confirm that requestBody, response, and schema references are normal.
  • If data models were imported, spot-check whether the schema can be read back normally.
  • If Apifox native format was imported, additionally confirm the module strategy, test case categories, test scenarios, and test suite references.
  • The final report must include the file path, quality metrics or export scope, import project, import counts, spot-check results, and remaining risks.

Non-violable rules

  1. Do not first hand-write a route extraction script; check the project's built-in generator first.
  2. Do not equate a large number of endpoints with a complete spec.
  3. Do not skip pre-import quality metrics.
  4. Do not repeatedly try imports by trial and error on an existing project.
  5. Do not ignore a large number of ignoreCount。
  6. Do not import a spec with chaotic tags that cannot be navigated by business domain as the final result.
  7. Do not treat a large project spec with very few schemas as the final version.

Common recovery

Symptom Handling
Import succeeds but only paths are present Check back whether the generator only extracts routes; continue looking for DTO/handler schemas
Very few schemas Use operations/writes/withBody/emptyObjectBodies to determine whether it is a route skeleton
A large number of empty bodies Check back the request DTO or the project generator
Apifox directories grouped by URL Rewrite operation tags and re-import into a clean project
A large number of ignoreCount Determine whether an existing project has been polluted; if necessary, create a clean project for verification
JSON.parse fails Check whether it is actually YAML; do not trust the extension
Duplicate modules appear after a second import of native format Check whether the default match-nameis used, whether the target module with the same name is unique; if necessary, use --module-map
The target project has multiple modules with the same name Don't let the CLI guess automatically, use --module-map "源模块名=目标模块ID"