Import/Export and Quality Gate
Prerequisite: Read
first. If there is a conflict between the old main entry and the domain rules of this skill, the current CLI help and this skill shall prevail.
Refer to the current CLI help for specific command parameters. Before import, focus on checking file format, OpenAPI quality gate, route skeleton risks, tags grouping, native format module strategy, ignoreCount and whether clean project verification is required. After Agent import, result confirmation must be done according to agentHints, list/get and necessary run/report; do not judge completion only based on the success returned by the import command.
When to Use
- Generate API spec from code repository, PRD, requirement document, test document, discussion record and import into Apifox.
- Import project data in formats like OpenAPI, Postman, HAR, Apifox native format.
- Configure auto-import.
- Export to OpenAPI, Markdown, HTML, Postman or Apifox native format.
- Need to determine whether the generated spec is just a "route skeleton".
- Migrate, backup or copy Apifox projects, 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 test scenario: Switch to , use
test-scenario import-steps
- Fine-grained maintenance of test scenario steps, variables, assertions or processors: Switch to .
Command Entry
Use the current CLI help to query parameters for
,
,
and
. Do not skip the following quality gate before import.
Core Principles
- Prioritize checking existing generators in the project, do not write extraction scripts first.
- Do not misjudge "complete path" as "complete interface spec".
- Must output quality metrics before import.
- Both completeness and readability must be accepted.
- When import strategy is uncertain, prioritize creating temporary/revised project for verification, do not pollute existing projects.
- A large number of in import results is a risk signal, not ordinary success.
- Apifox directory grouping depends on OpenAPI operation tags.
- Do not assume file extension represents actual format.
Standard Process
Step 0. Clarify Task Type
First judge which type of task the user wants to perform:
| Task | Next Step |
|---|
| Generate spec from code repository, PRD, document and import | Proceed to Step 1 |
| Directly import existing files | Start from Step 3 |
| Configure auto-import | Read current CLI help and schema first, then create configuration |
| Export document or OpenAPI | Use export command directly, check if file is generated after export |
| Migrate or backup Apifox project | Use Apifox native format for export and import, and confirm module import strategy |
| Import existing resources into test scenario | Switch to , do not use OpenAPI import |
If the user does not specify target project, team, import strategy or whether project creation is allowed, judge based on context first; ask only one minimal necessary question if uncertain.
Step 1. Search for Existing Generators in the Project
When encountering requirements like "Generate API spec / document / type from source code/document/PRD/test document/discussion", first search if the following exist in the project:
text
openapi
swagger
routegen
route-gen
docs generator
api docs
schema generator
cmd/openapi
cmd/*openapi*
Correct approach:
- Run the generator provided by the project first.
- Prioritize tools that can extract handler request/response struct, DTO, schema.
- Do not write scripts to extract paths from router files first, otherwise it is easy to only get method + path skeleton.
If no generator is found, consider generating spec from framework routes, comments, DTO, schema, tests or documents; after generation, must continue with quality gate from Step 3 onwards.
Step 2. Generate Spec and Confirm File Format
- Run the project's built-in generator or official generation command.
- Save the original output, do not directly overwrite existing files of the user.
- Do not judge format by extension.
- Before reading the generated file, check the beginning of the file or use a JSON/YAML-supported parser.
- The generator may output YAML to a file; if it is actually YAML, rename it to or parse it as YAML.
Step 3. Count Pre-Import Quality Metrics
Before import, must actually parse the generated OpenAPI file and report real statistical values. Do not use sample values, default values or placeholder values.
Must count:
| Metric | Meaning | Purpose |
|---|
| Number of OpenAPI paths | Judge interface scale |
| Number of actual operations | Judge import scale |
| Number of | Judge model completeness |
| Number of write interfaces like POST/PUT/PATCH | Judge body coverage target |
| Number of write interfaces with requestBody | Judge requestBody coverage |
| Number of requestBody schemas that are empty objects | Judge whether it is a route skeleton |
When outputting, must write "real statistical results", for example, using table or JSON is acceptable, but each value must come from the current file parsing result.
Step 4. Judge Spec Completeness
- Do not judge quality by fixed schema count.
- For small, pure GET, health check, webhook pass-through, no JSON body projects, is acceptable.
- For large projects with many interfaces and many write interfaces but very few schemas, it is regarded as a suspected route skeleton spec.
- Missing body or empty in a large number of POST/PUT/PATCH is a strong risk signal.
- Only method + path cannot prove that requestBody, response, schema are complete.
Risk judgment:
| Phenomenon | Judgment | Handling |
|---|
| Large interface scale, many write interfaces, but very few schemas | Suspected route skeleton spec | Continue to check DTO, handler request/response struct, in-project generator or document source |
| Many write interfaces, but withBody coverage is obviously insufficient | Incomplete requestBody | Continue to supplement request DTO or switch generator |
| Many emptyObjectBodies | Strong risk, may be just empty shell body | Do not import as final spec |
| Small, pure GET, health check, webhook pass-through | Few schemas may be reasonable | Judge combined with business form, do not force failure |
If judged as route skeleton spec, do not import as final version; at most import to temporary project for exploration.
Step 5. Validate Tags and Document Readability
API spec not only needs complete models, but also needs to be readable, navigable and reasonably grouped in Apifox.
Must check:
- Whether operations have business-oriented .
- Whether tags are grouped by business domain, not mechanically grouped by URL path.
- Whether schema is completely retained.
- Whether operationId, summary, description are readable.
Recommended tags format:
yaml
paths:
/api/v1/<resource>:
post:
tags:
- <Business Domain Name>
Not recommended to have directories mechanically expanded by technical path after import, for example:
It is more recommended to set tags according to product module, business domain, resource domain or user-understandable functional domain, so that the directory in Apifox client serves business navigation instead of code path restoration.
If the tags of generator output are obviously too rough or mechanically come from technical paths, for example, a large number of interfaces fall under directories like
,
,
,
,
, must stop before import, first ask the user whether to allow generating a revised spec with more reasonable tags and cleaner project documentation. Do not import this spec as the final project before user agrees.
Step 6. Select Import Project
- When import strategy is uncertain, prioritize creating temporary/revised project for verification.
- Do not repeatedly import new spec to pollute existing projects.
- If skeleton spec has been imported into existing project, importing complete spec again may result in old interface ignore, new interface append, and project混杂.
- Temporary project naming should express version and purpose, for example , .
Step 7. Execute Import and Check Results
Do not only look at command success after import, but also check result count.
If
in import results is obviously high, cannot regard "command execution success" as "import quality qualified". Must continue to judge:
- Whether imported into existing project.
- Whether interface matching strategy does not meet expectations.
- Whether old spec and new spec are mixed.
- Whether should re-import using clean project.
Step 7A. Apifox Native Format Import Strategy
Apifox native format is suitable for project migration, backup, cross-project copy and partial resource relocation. Common commands:
bash
apifox import --project <projectId> --format apifox --file ./project.apifox.json
The default module strategy is
: import into existing module when source module name uniquely matches target project module name, create new module when no match. When importing the same project for the second time, prioritize using default strategy to avoid duplicate creation of modules with the same name.
bash
apifox import --project <projectId> --format apifox --file ./project.apifox.json --module-import-mode match-name
If the test goal is to copy a set of new modules each time, use
:
bash
apifox import --project <projectId> --format apifox --file ./project.apifox.json --module-import-mode new
When there are multiple modules with the same name in the target project, or precise control of source module destination is needed, use
. It can be passed repeatedly, and has higher priority than
:
bash
apifox import --project <projectId> --format apifox --file ./project.apifox.json \
--module-map "Store API=8049476" \
--module-map "Admin API=8049482"
Common mapping expressions:
| Expression | Purpose |
|---|
"Source Module Name=Target Module ID"
| Import to specified existing module |
"source:Source Module ID=Target Module ID"
| Precisely specify using source module ID when source modules have the same name |
"Source Module Name=default"
| Import to default module of target project |
| Only let this source module create new |
Specifying only part of source modules is also acceptable; unspecified source modules continue to be processed according to
. It is recommended to use module ID for target module to avoid ambiguity of modules with the same name in target project.
After import, must verify:
- Whether module quantity meets expectations, no unintentional new modules with the same name should be added in secondary import.
- Whether quantity of resources like API, Schema, test case, test scenario, WebSocket, Socket.IO meets import results.
- Whether single interface test case classification is visible.
- If test suite is imported, spot-check whether scenarios and case references in the suite point to new project resources.
Step 7B. Apifox Native Format Export Strategy
Full backup or migration:
bash
apifox export --project <projectId> --format apifox --output ./project.apifox.json
Export only specified interfaces or directories, suitable for partial relocation or minimal reproduction:
bash
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 tags, suitable for delivery by business domain:
bash
apifox export --project <projectId> --format apifox --scope tags --include-tags pet,store --exclude-tags deprecated --output ./tagged.apifox.json
By default, interface debugging and single interface cases are included; if only interface definition is needed, explicitly turn off:
bash
apifox export --project <projectId> --format apifox --no-include-api-cases --output ./apis-only.apifox.json
After export, check if file exists, size is reasonable, and perform an import verification in temporary project, especially before sending to others or using for migration.
Step 8. Read Back Verification and Report
- Read back interface list, confirm total interface count is consistent with import results.
- Spot-check at least one read interface and one write interface; for write interface, confirm requestBody, response, schema reference are normal.
- If data model is imported, spot-check whether schema can be read back normally.
- If Apifox native format is imported, additionally confirm module strategy, test case classification, test scenario and test suite references.
- Final report must include file path, quality metrics or export scope, import project, import count, spot-check results and remaining risks.
Non-Violable Rules
- Do not write route extraction scripts first, check in-project generators first.
- Do not equate large number of interfaces with complete spec.
- Do not skip pre-import quality metrics.
- Do not repeatedly import and test on existing projects.
- Do not ignore a large number of .
- Do not import spec with messy tags and unable to navigate by business as final result.
- Do not regard spec of large project with very few schemas as final version.
Common Recovery
| Phenomenon | Handling |
|---|
| Import successful but only paths exist | Check if generator only extracts routes, continue to find DTO/handler schema |
| Very few schemas | Judge whether it is route skeleton combined with operations/writes/withBody/emptyObjectBodies |
| A large number of empty bodies | Check request DTO or project generator |
| Apifox directory grouped by URL | Rewrite operation tags and re-import to clean project |
| A large number of ignoreCount | Judge whether existing project is polluted, create clean project for verification if necessary |
| JSON.parse failed | Check if it is actually YAML, do not trust extension |
| Duplicate modules appear after secondary import of native format | Check if default is used, whether target modules with same name are unique; use if necessary |
| Multiple modules with same name in target project | Do not let CLI guess automatically, use --module-map "Source Module Name=Target Module ID"
|