Organize the capabilities in the SKSPIOT project that are "directly exposed Service interfaces without a Controller" into an OpenAPI 3.1 JSON file, for the user to manually import into Apifox.
Do not attempt to create or update interfaces directly through the apifox MCP anymore. The current process has only one goal:quickly and stably generate an importable file.
How to use
/ac-api <需求描述>
Typical input:
/ac-api 把充电桩概况接口导出成 Apifox 可导入的 OpenAPI 文件/ac-api 根据 BusinessCenter4EVChargingStation 的 overviewEVChargingStation 生成 OpenAPI 3.1 JSON/ac-api 扫描这个模块,按接口逐个导出 OpenAPI 文件
Default conventions
| Item | Default value |
|---|---|
| Output root directory | .claude/OpenAPI |
| Date directory | YYYY-MM-DD |
| File name | HH-MM_BusinessCenter.method.openapi.json |
| OpenAPI version | 3.1.0 |
| Request address | http://127.0.0.1:8888 |
| Request path | /json-adapter |
| HTTP Method | POST |
| Content-Type | application/json |
| Export granularity | One interface per file |
Note:
- Only one
POST /json-adapter - If the user wants to export multiple business methods, generate multiple files
- File sorting depends on the date directory + time-prefixed file name; do not change it to another format
Scope of application
Only used for SKSPIOT Smart Park IoT Platform, and must conform to the following interface conventions:
- No Controller layer
- Use on the class or interface
@BusinessCenterDescriptor - Use on the method
@BusinessDescriptor - All requests use
POST Content-Typefixed toapplication/json- The request body is uniformly:
{
"bid": "<Service全限定名>.<业务方法名>",
"params": {
"<参数名>": {}
},
"passport": "{{access_token}}"
}
If the current project does not conform to this set of rules:
- Stop applying this skill immediately
- Clearly tell the user that this is a SKSPIOT-specific skill
- Do not force an OpenAPI file to fit
Execution constraints
- Read before doing: first locate the annotations, method signature, parameter types, and return type, then decide how to export
- Speed first: prioritize directly reading the target method name, interface parameters, and return type; only continue tracing related types when DTO/VO fields need to be expanded, and do not scan the entire source tree first when the file/method is already known
- No guessing: do not guess package names, do not guess
bid, do not guess parameter names, do not guess the return structure - Must clarify: when information is missing, the project scope is unclear, or the interface cannot be pinpointed accurately, use
AskUserQuestionto ask first - Automatic example inference: if parameters and return values have no explicit example or schema, infer from the real parameters/return entities first; when evidence is insufficient, fall back to a minimal placeholder instead of hardcoding a generic success object
- Return field descriptions prioritize evidence:
dataField descriptions inside should prioritize field annotations (such as@Schema/@ApiModelProperty) and field Javadoc/comments; do not pass off autocomplete text as real field descriptions - Insufficient evidence must be explicitly stated: if return fields lack annotations/Javadoc/comments, exporting may continue, but the delivery result must clearly point out which field descriptions lack code evidence, and must not be silently skipped
- Type ambiguity must not be silently matched:When there is ambiguity from duplicate DTO/VO names in the return type or field type, do not default to selecting the first matching result; you must conservatively degrade or explicitly indicate the conflict point
- Fixed response wrapper:The return value is uniformly generated as
{ "code": "success", "success": true, "data": <返回实体>, "msg": "操作成功" }, wheredatais derived based on the interface's actual returned entity - Do not claim that it has been synced to Apifox:Only generate the import file here; do not write directly to Apifox
- Prefer script generation:The OpenAPI JSON is generated by a local script; do not let the large model directly handwrite large sections of OpenAPI documentation
- Do not read back scripts and artifacts:During normal execution, do not read back
generate_openapi.py、export_openapi_from_java.py, and do not read back after generation.openapi.json/.metadata.json; this is only allowed when debugging the skill itself - Minimal artifact principle:Prefer generating an importable, readable, and sortable JSON file, without additionally extending complex fields
- One interface per file:Do not cram multiple business methods into the same OpenAPI file
Items that must be confirmed first
In the following situations, ask first; do not execute directly:
| Scenario | Questions that must be confirmed |
|---|---|
| The user only says "export interface" | Which Service, which method, and which module should be exported? |
| The user wants batch export | Should multiple files be generated separately for each method, or should only a few key interfaces be exported first? |
@BusinessDescriptor.name is inconsistent with the method name |
bid Which one should be taken for the last level? |
Recognition rules
1. Identify the business center
Prioritize locating the @BusinessCenterDescriptoron the class or interface, and confirm that this is an externally exposed business center.
2. Identify the specific interface
Locate the @BusinessDescriptoron the method within the business center, and extract at least the following information:
| Field | Source |
|---|---|
| Fully qualified name of the business center class/interface | Java declaration location |
| Short name of the business center | Class name or interface name |
| Method name | Java method signature |
| Business method name | @BusinessDescriptor.name, and if missing, fall back to the method name |
| Interface description | @BusinessDescriptor.desc |
| Return description | @BusinessDescriptor.returnDesc |
| Parameter list | Java method parameter name + parameter type |
| Return type | Java method return type |
| Chinese field description | Field annotation > field comment/Javadoc; when there is no evidence, clearly mark the gap, and do not treat autocomplete as a real description |
| Evidence | file_path:line_number |
3. bid generation rules
bid consists of two parts:
- Fully qualified name of the Service exposed interface
- Business method name
Format:
<serviceFqcn>.<businessMethod>
Example:
base.business.energy.service.BusinessCenter4EVChargingStation.overviewEVChargingStation
Note:
- Prioritize using Externally exposed Service interface/business center definition, and do not mistakenly use the implementation class
- For the method segment, prioritize taking
@BusinessDescriptor.name - If
@BusinessDescriptor.nameis missing, then use the Java method name - If the annotation value, method name, and existing call examples conflict with each other, you must stop and ask the user; do not guess
4. Request body assembly rules
Requests uniformly use:
- Method:
POST - URL:
http://127.0.0.1:8888/json-adapter - Header:
Content-Type: application/json
The request body has a fixed outer structure:
{
"bid": "<serviceFqcn>.<businessMethod>",
"params": {
"<参数名>": {}
},
"passport": "{{access_token}}"
}
params rules:
- Single-parameter method: keep the parameter name; do not omit the outer key
- Multi-parameter method: expand one by one into keys according to the method parameter names
- No-parameter method: use an empty object
{} - Example values: prefer to extract from existing code, example requests, tests, and documentation; if there is no evidence, automatically infer reasonable default values based on parameter names and types
Generate script
Uniformly use the local script:
python skills/ac-api/scripts/generate_openapi.py --input <metadata.json>
python skills/ac-api/scripts/export_openapi_from_java.py --source <Java文件或目录> --save-metadata
Also supports stdin + automatically writing metadata:
python skills/ac-api/scripts/generate_openapi.py --input - --save-metadata <<'EOF'
{
"serviceFqcn": "base.business.energy.service.BusinessCenter4EVChargingStation",
"serviceName": "BusinessCenter4EVChargingStation",
"methodName": "overviewEVChargingStation",
"businessMethod": "overviewEVChargingStation",
"summary": "充电桩概况",
"description": "充电桩概况",
"returnType": "EVOverviewEVChargingStationDTO",
"returnDesc": "EvChargingStationPowerDataStatistics",
"parameters": [
{
"name": "vo",
"type": "EVSPageRspVO",
"example": {
"projectId": 1
}
}
],
"responseExample": {},
"evidence": [
"src/main/java/.../BusinessCenter4EVChargingStation.java:42"
]
}
EOF
After enabling --save-metadata , the script will additionally write a .metadata.jsonin the same directory, for easy source tracing.
Metadata file format
Before calling the script, first prepare asmall metadata JSON, then hand it to the script to generate the final OpenAPI file.
Minimal example:
{
"serviceFqcn": "base.business.energy.service.BusinessCenter4EVChargingStation",
"serviceName": "BusinessCenter4EVChargingStation",
"methodName": "overviewEVChargingStation",
"businessMethod": "overviewEVChargingStation",
"summary": "充电桩概况",
"description": "充电桩概况",
"returnType": "EVOverviewEVChargingStationDTO",
"returnDesc": "EvChargingStationPowerDataStatistics",
"parameters": [
{
"name": "vo",
"type": "EVSPageRspVO",
"example": {
"projectId": 1
}
}
],
"responseExample": {},
"evidence": [
"src/main/java/.../BusinessCenter4EVChargingStation.java:42"
]
}
Script output rules
The script will automatically generate:
| Item | Rule |
|---|---|
| Output directory | .claude/OpenAPI/YYYY-MM-DD/ |
| File name | HH-MM_BusinessCenter.method.openapi.json |
| metadata file | HH-MM_BusinessCenter.method.metadata.json(only when --save-metadata is used) |
openapi |
3.1.0 |
servers[0].url |
http://127.0.0.1:8888 |
paths |
Generate only one /json-adapter |
operationId |
BusinessCenter.method |
If the user explicitly requires consistent timestamps, the same minute value can be reused during the same export round.
Recommended execution flow (mandatory 4 steps)
Step 1: Confirm scope
First confirm which Service, which method, and which module the target is.
- Single interface: continue directly
- Multiple interfaces: clearly tell the user that multiple single interface per file
- Unclear scope: ask first, do not guess
Step 2: Read the necessary code
Only read the code evidence necessary for generating the current interface:
@BusinessCenterDescriptorthe class/interface where@BusinessDescriptorthe method where- Method signature
- Necessary parameter type and return type definitions
Constraints:
- Known file path: read the target file directly
- Known class name/method name: locate precisely before reading
- Only continue tracing DTO / VO when fields need to be expanded
- During normal execution, it is forbidden to read back the skill's built-in scripts and existing generated artifacts
Step 3: Organize metadata and generate immediately
After organizing the minimal metadata, directly call the script to generate, without additional back-and-forth checks.
The minimal metadata must at least include:
| Item | Content |
|---|---|
serviceFqcn |
Service fully qualified name |
serviceName |
Service short name |
methodName |
Java method name |
businessMethod |
@BusinessDescriptor.name or method name |
summary |
Business description |
description |
Business description or supplementary explanation |
returnType |
Java return type |
returnDesc |
@BusinessDescriptor.returnDesc |
parameters |
Parameter names, types, examples |
responseExample / responseSchema |
Provide if available |
evidence |
file_path:line_number |
Recommended command:
python skills/ac-api/scripts/generate_openapi.py --input <metadata.json> --save-metadata
Or:
python skills/ac-api/scripts/generate_openapi.py --input - --save-metadata
Only use this when the user explicitly requests "direct one-stop export from Java":
python skills/ac-api/scripts/export_openapi_from_java.py --source <Java文件或目录> --save-metadata
Step 4: Deliver the result directly
After running the script, return directly:
- Output file path
- Whether metadata was generated
- Corresponding
bid - Key code evidence
Do not do these things:
- Do not read back
generate_openapi.py/export_openapi_from_java.py - Do not read back the just-generated
.openapi.json/.metadata.json - Do not loop back to the script or artifacts just to "confirm"
Only whendebugging the skill itselfortroubleshooting script errorsare exceptions allowed.
Output requirements
First provide a results summary table:
| Item | Content |
|---|---|
| Output file | <实际文件路径> |
| OpenAPI version | 3.1.0 |
| Request address | http://127.0.0.1:8888/json-adapter |
| API name | <summary> |
bid |
<serviceFqcn>.<businessMethod> |
| Evidence | file_path:line_number |
Then add:
- Which code evidence was used (
file_path:line_number) - Which fields were inferred from the code
- Which example values came from the user or existing samples
- If the return schema only uses basic placeholders, state this clearly
Failure handling
- Cannot find
@BusinessCenterDescriptor: Tell the user that the current code does not conform to the SKSPIOT rules, or that the target location needs to be provided - Cannot find
@BusinessDescriptor: Tell the user that no exposable methods were found, and provide the locations checked - Cannot confirm
bid: List the conflicts and ask - Parameter examples missing: Exporting a minimal empty object is allowed, but this must be stated clearly
- Return field descriptions lack annotation/Javadoc/comment evidence: Continuing the export is allowed, but fields lacking description evidence must be listed
- Return types or field types have duplicate-name ambiguity: Do not silently select a candidate; degrade conservatively or clearly list the conflicting candidates
- Return structure cannot be reliably inferred: Exporting a basic schema first is allowed, but this must be stated clearly
- Script execution failed: Show the error message as-is, and state whether the failure occurred in the metadata stage or the script generation stage