API调试：完整实践与解答

需能阅读 HTTP 请求与 JSON。本文对照离线笔记接口资料：GET /notes/1、/notes/999、/notes/0 分别约定 200、404、400，并提供 OpenAPI 3.1 与响应样本；example.invalid 是占位地址，阅读不需要服务、Postman 或账号。 示例未在本轮执行；本页完整源码与README列出输入、阅读顺序和预期。

API 完整静态契约

API完整静态契约给出OpenAPI3.1、两条HTTP请求、成功响应和错误响应。示例未执行；它是可审阅的接口资料，不含服务、模拟器、账号配置或联网客户端。

API 无效输入练习

题目：GET /notes/0应当与不存在的正整数ID相同吗？

参考答案

契约规定ID最小为1，0属于参数校验失败应返回400；合法但不存在的ID返回404。区分输入错误与资源不存在才能指导调用方修正。

API 敏感数据清理

API敏感数据清理先检查请求头、URL查询和响应样本是否包含真实令牌或个人信息。本例只有虚构标题；还原文件不撤销真实凭据，若读者未来误提交密钥须按提供方流程轮换。

完整源码、配置与输入

下列文件与仓库同源，包含完整实现和输入；不是运行证明。部分练习只需人工阅读配置，不强制构造模拟器。

openapi.yaml

openapi: 3.1.0
info:
  title: Offline Note Contract
  version: 1.0.0
servers:
  - url: https://example.invalid
paths:
  /notes/{id}:
    get:
      operationId: getNote
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: Existing note
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Note'
              example:
                id: 1
                title: Read the contract
        '400':
          description: Invalid ID
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: about:blank
                title: Invalid ID
                status: 400
        '404':
          description: Note not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: about:blank
                title: Note not found
                status: 404
components:
  schemas:
    Note:
      type: object
      additionalProperties: false
      required: [id, title]
      properties:
        id:
          type: integer
          minimum: 1
        title:
          type: string
          minLength: 1
    Problem:
      type: object
      additionalProperties: false
      required: [type, title, status]
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
          enum: [400, 404]

requests.http

# Static request documents only. DO NOT SEND.
@baseUrl = https://example.invalid

### Existing note -> 200 application/json
GET {{baseUrl}}/notes/1
Accept: application/json

### Missing note -> 404 application/problem+json
GET {{baseUrl}}/notes/999
Accept: application/problem+json

### Invalid ID -> 400 application/problem+json
GET {{baseUrl}}/notes/0
Accept: application/problem+json

success.json

{"id": 1, "title": "Read the contract"}

not-found.json

{"type": "about:blank", "title": "Note not found", "status": 404}

invalid.json

{"type": "about:blank", "title": "Invalid ID", "status": 400}

requirements.txt

# OpenAPI 3.1.0 document and HTTP plain-text request syntax.
# No server, Postman workspace, client package or account is required to read.

项目README与完整依赖

README提供前置、完整自跑或阅读方式、预期、失败案例与恢复清理。本轮没有执行任何示例、产品CLI、模型或外部API。

# API调试：完整教学包

示例未执行。全部输入为教学虚构资料，不能用于真实账号、生产数据或外部系统。

## 前置与依赖

OpenAPI3.1资料阅读器可选；不需Postman、服务或账号。example.invalid不是服务地址。

## 文件与输入

- `openapi.yaml`：本包完整文件。
- `requests.http`：本包完整文件。
- `success.json`：本包完整文件。
- `not-found.json`：本包完整文件。
- `invalid.json`：本包完整文件。
- `requirements.txt`：本包完整文件。

## 读者将来自跑或阅读

复制本包所有文件到独立目录，在该目录作为当前工作目录。以下是读者自用资料，本轮禁止执行。

```text
只对照openapi.yaml、requests.http与三份响应文本，不发送任何请求。
```

## 正常预期

/notes/1对应200和success.json；/notes/999对应404；/notes/0对应400。

## 失败案例与恢复

将id写成0违反minimum；缺title违反required；额外字段违反additionalProperties:false。未运行schema验证器。

## 清理及能力边界

保留本地文件即可；不创建远端工作区，不执行请求，不需要撤回。

## 来源

- [官方依据](https://spec.openapis.org/oas/v3.1.0)（2026-10-17资料核对；不是运行证明）

依据与适用范围

• 本课官方依据，资料核对日2026-10-17。

本课完成的是列明任务的理论与静态资料，不代表产品全部能力或三平台运行通过。历史文档保留旧URL；涉及账号、版本、价格与界面位置时，以对应官方资料及实际授权环境为准。