SuperAPI AI Directory

ac-api

Coding & development

View repository

Updated 10-16 09:59

About this skill

Apifox - Generate OpenAPI 3.1 import file

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-Type fixed to application/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 AskUserQuestion to 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:data Field 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": "操作成功" }, where data is 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:

  1. Fully qualified name of the Service exposed interface
  2. 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.name is 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:

  • @BusinessCenterDescriptor the class/interface where
  • @BusinessDescriptor the 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