使用Swagger创建API规范时遇“Unknown Error”报错求助

开发者阿泽

2026-5-22

嘿兄弟，我一眼就瞅到你这Swagger规范的问题了，结合你说的Items:行报“Unknown Error”，再看你贴的代码片段，大概率是这几个坑导致的——都是我之前踩过的：

1. 先补全截断的语法

你代码里的produces字段值写了appli...，这明显是没写完啊！应该补全成application/json。Swagger解析器遇到这种不完整的语法会直接混乱，甚至把错误定位到后面的行（比如你说的Items:那行），先把这个补全再说。

2. YAML大小写敏感！`Items`必须改成小写`items`

这是Swagger 2.0最容易踩的坑之一：在定义数组类型的Schema时，官方要求的字段名是小写的items，而不是大写开头的Items。YAML是严格区分大小写的，解析器根本认不出大写的Items，自然会报“Unknown Error”。

3. 给你贴个修复后的完整示例参考

我把你代码里的问题都修正了，还补了一个Todo列表的响应示例，你可以直接参考：

swagger: "2.0"
info:
  version: "0.0.1"
  title: Todo API
host: localhost:10010
basePath: /
consumes:
  - application/json
produces:
  - application/json
paths:
  /todos:
    get:
      summary: 获取所有待办事项
      responses:
        200:
          description: 成功返回待办事项列表
          schema:
            type: array
            items:  # 这里必须是小写！
              type: object
              properties:
                id:
                  type: integer
                title:
                  type: string
                completed:
                  type: boolean