8.9 KiB
API Documentation Coverage Implementation Plan
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Give all 35 Spring MVC routes Chinese module names, operation descriptions, parameter documentation, response documentation, and readable core request/response schemas in Swagger UI.
Architecture: Keep documentation next to the code it describes: controller-level @Tag, handler-level @Operation and @ApiResponse, parameter-level @Parameter, and DTO-level @Schema. Add a reflection-based coverage test so future routes cannot silently omit documentation, then verify the generated /v3/api-docs at runtime.
Tech Stack: Java 8, Spring Boot 2.3.4, Springdoc OpenAPI 1.8.0, Swagger annotations 2.2.20, JUnit 4.13
Task 1: Add documentation coverage tests
Files:
-
Create:
src/test/java/com/inspect/nvr/config/ApiDocumentationCoverageTest.java
The test must scan CameraController, DahuaController, FileController, InfraredController, IvsCameraController, IvsServerController, and Test. A handler is any declared method carrying GetMapping, PostMapping, PutMapping, DeleteMapping, PatchMapping, or method-level RequestMapping.
For every controller, assert a non-empty Chinese @Tag. For every handler, assert a non-empty @Operation.summary and at least one @ApiResponse. Assert the total is exactly 35.
Assert that these API-facing models have a non-empty class-level @Schema.description: Camera, NvrInfo, TemperatureData, InfraPictureInfo, InfraredBox, InfraredInfo, PtzControlParam, PtzControlResult, SnapshotCommandParam, SnapshotCommandResult, SnapshotInfoListParam, SnapshotInfoListResult, IvsPresetListView, Login, IvsResult, IvsVideoRtspVo, IvsVideoRtspView, IvsDevChanListVo, ResultEntity, and FileReturn.
$env:JAVA_HOME='C:\Program Files\Java\jdk1.8.0_191'
$env:Path="$env:JAVA_HOME\bin;$env:Path"
mvn -Dtest=ApiDocumentationCoverageTest test
Expected: failures report missing @Tag, @Operation, @ApiResponse, and @Schema documentation.
Task 2: Document all controller modules and operations
Files:
-
Modify:
src/main/java/com/inspect/nvr/controller/CameraController.java -
Modify:
src/main/java/com/inspect/nvr/controller/DahuaController.java -
Modify:
src/main/java/com/inspect/nvr/controller/FileController.java -
Modify:
src/main/java/com/inspect/nvr/controller/InfraredController.java -
Modify:
src/main/java/com/inspect/nvr/controller/IvsCameraController.java -
Modify:
src/main/java/com/inspect/nvr/controller/IvsServerController.java -
Modify:
src/main/java/com/inspect/nvr/controller/Test.java
Use these exact module names:
| Controller | Tag name | Description |
|---|---|---|
CameraController |
通用摄像机 |
统一封装海康和大华摄像机的预置位与红外测温能力 |
DahuaController |
大华设备 |
大华 NVR 登录、测温、云台控制和抓图接口 |
FileController |
文件管理 |
文件上传接口 |
InfraredController |
红外测温 |
海康红外测温、抓图、图片分析和 CSV 下载接口 |
IvsCameraController |
IVS摄像机 |
IVS 平台预置位、抓图任务和图片下载接口 |
IvsServerController |
IVS联调/模拟 |
IVS 协议联调接口；当前包含固定或模拟响应，请勿作为生产业务结果 |
Test |
联调测试 |
FTPS 等联调测试接口，请勿在生产环境调用 |
Use the following exact summaries for the 35 routes; each handler also receives a successful @ApiResponse(responseCode = "200", description = "请求成功"), with more specific descriptions for binary responses and login/test routes.
| Route | Summary |
|---|---|
/hw/cameraYzwHikVision |
查询海康摄像机预置位 |
/hw/cameraHong |
统一读取红外测温数据 |
/hw/test |
测试异步任务超时处理 |
/dahua/login |
登录大华 NVR |
/dahua/StartRemote |
读取大华红外测温数据 |
/dahua/cameraControl |
控制大华云台跳转预置位 |
/dahua/Picture |
抓取大华摄像机图片 |
/file/upload |
上传文件 |
/login |
登录海康 NVR |
/cameraHong |
读取海康红外测温数据 |
/cameraAngleJump |
控制海康云台跳转预置位 |
/camera |
抓取海康 NVR 图片 |
/cameraHk |
抓图并计算红外温度 |
/ir/capturePicture |
设置红外图片分析参数 |
/ir/picAnalyse |
提交红外图片算法分析 |
/device/radiometry-temper/{cameraCode} |
查询测温规则结果（模拟） |
/ir/downloadCsv |
下载红外温度 CSV |
/ir/addBoxData |
添加红外分析框（模拟） |
/ir/deleteBoxData |
删除红外分析框（模拟） |
/ir/selectBoxData |
查询红外分析框（模拟） |
/ir/status |
查询红外流关闭状态 |
/device/ptzpresetlist/{cameraCode}/{domainCode} |
查询 IVS 摄像机预置位 |
/device/ptzcontrol |
控制 IVS 摄像机云台并测温 |
/platform/platformSnapshot/{cameraCode}/{domainCode} |
创建平台抓图任务 |
/platform/snapshotList |
查询平台抓图结果 |
/downloadfile_old |
下载抓图文件（旧版） |
/downloadfile |
下载抓图文件 |
/digest |
检测 Digest 抓图是否可用 |
/common/keepAlive2 |
IVS心跳检测（模拟） |
/loginInfo/login2/v1.0 |
IVS登录（模拟） |
/device/ptzpresetlist2/{cameraCode}/{domainCode} |
查询IVS预置位（模拟） |
/video/rtspurl2/v1.0 |
获取RTSP播放地址（模拟） |
/device/deviceList2/v1.0 |
查询IVS设备列表（模拟） |
/hw/test2 |
测试FTPS批量下载 |
/hw/test3 |
测试FTPS文件读取 |
Add @Parameter descriptions and safe examples to every @PathVariable and @RequestParam. Mark filesessionid as a temporary image session identifier and never include credentials in examples. Document /dahua/Picture, /downloadfile_old, and /downloadfile as image/jpeg; document /ir/downloadCsv as text/csv; document /file/upload parameters as filename and multipart file.
mvn -Dtest=ApiDocumentationCoverageTest test
Expected: route count remains 35 and controller/handler coverage assertions pass; DTO assertions may still fail until Task 3.
Task 3: Document API-facing schemas
Files:
-
Modify the 20 DTO classes listed in Task 1 under
src/main/java/com/inspect/nvr/domain/**.
Add @Schema(description = "...") to each listed class, using Chinese descriptions that match its role: device login, camera operation, temperature result, IVS command/result, snapshot command/result, or generic response.
Annotate API-visible fields with @Schema(description = "...", example = "..."). Use documentation-only examples such as 192.168.1.100, 8000, admin, camera-001, domain-001, and 1; do not include real passwords, RTSP URLs, FTP credentials, or internal production addresses. Password examples must be omitted or use writeOnly = true without a value.
mvn -Dtest=ApiDocumentationCoverageTest test
Expected: all documentation coverage tests pass with zero failures and zero errors.
Task 4: Preserve parameter names and validate generated OpenAPI
Files:
-
Modify:
pom.xml
Add <parameters>true</parameters> to the existing maven-compiler-plugin configuration without changing source or target level.
mvn test -DskipTests=false
Expected: all 3,505+ main sources compile and both Swagger tests pass.
mvn spring-boot:run '-Dspring-boot.run.arguments=--server.port=18080'
Query http://127.0.0.1:18080/v3/api-docs and verify:
-
exactly 35 paths;
-
seven expected Chinese tags;
-
every operation has a Chinese summary and at least one response;
-
request bodies reference documented schemas;
-
binary endpoints advertise
image/jpegortext/csv.
Run scoped git diff --check and git status --short. Do not stage or commit any file. Confirm the user's pre-existing staged file list is unchanged.