# 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` - [ ] **Step 1: Add a reflection test for all controllers and routes** 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. - [ ] **Step 2: Add a core DTO schema test** 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`. - [ ] **Step 3: Run the focused test and verify RED** ```powershell $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` - [ ] **Step 1: Add controller tags** Use these exact module names: | Controller | Tag name | Description | |---|---|---| | `CameraController` | `通用摄像机` | `统一封装海康和大华摄像机的预置位与红外测温能力` | | `DahuaController` | `大华设备` | `大华 NVR 登录、测温、云台控制和抓图接口` | | `FileController` | `文件管理` | `文件上传接口` | | `InfraredController` | `红外测温` | `海康红外测温、抓图、图片分析和 CSV 下载接口` | | `IvsCameraController` | `IVS摄像机` | `IVS 平台预置位、抓图任务和图片下载接口` | | `IvsServerController` | `IVS联调/模拟` | `IVS 协议联调接口；当前包含固定或模拟响应，请勿作为生产业务结果` | | `Test` | `联调测试` | `FTPS 等联调测试接口，请勿在生产环境调用` | - [ ] **Step 2: Add operation and response documentation** 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文件读取` | - [ ] **Step 3: Document non-body parameters and binary responses** 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. - [ ] **Step 4: Run the controller coverage test** ```powershell 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/**`. - [ ] **Step 1: Add class-level schema descriptions** 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. - [ ] **Step 2: Add field descriptions and safe examples** 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. - [ ] **Step 3: Run the coverage test and verify GREEN** ```powershell 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` - [ ] **Step 1: Preserve Java method parameter names** Add `true` to the existing `maven-compiler-plugin` configuration without changing source or target level. - [ ] **Step 2: Run all tests** ```powershell mvn test -DskipTests=false ``` Expected: all 3,505+ main sources compile and both Swagger tests pass. - [ ] **Step 3: Start the application on a temporary port and inspect the document** ```powershell 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/jpeg` or `text/csv`. - [ ] **Step 4: Review final local-only changes** 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.