Swagger Editor 3.0：如何编写Java URI/Set/Map对应的组件Schema

我会帮你解决ShowStaticInfo类对应的Swagger YAML Schema定义问题，同时修复原代码里的语法、字段匹配错误，下面是完整的修正版本：

openapi: "3.0.1"
info:
  title: Mobile backend
  version: 1.0.0
  license:
    name: Apache 2.0
servers:
  - url: https://development.cybercom.com/services/6
    description: Development server
  - url: https://staging.cybercom.com/services
    description: Staging server
  - url: https://production.cybercom.com/services
    description: Production server
paths:
  /buildinfo:
    get:
      description: Returns the build information (Version and Time stamp).
      operationId: getBuildInfo
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildInfo'
      parameters:
        - in: header
          name: LBPATH
          schema:
            type: string
  /countries/{countryId}/cities/{cityId}/showinfo/static:
    get:
      description: Returns a list of static show information for a city.
      operationId: getShowStaticInfo
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShowStaticInfo'
      parameters:
        - in: path
          name: countryId
          required: true
          schema:
            type: string
        - in: path
          name: cityId
          required: true
          schema:
            type: string
        - in: header
          name: Accept-Language
          schema:
            type: string
        - in: header
          name: LBPATH
          schema:
            type: string
components:
  schemas:
    BuildInfo:
      properties:
        version:
          type: string
        timestamp:
          type: string
        status:
          type: string
    # 先定义Tag Schema，因为ShowStaticInfo依赖它
    Tag:
      type: object
      # 这里根据你的Tag类实际字段调整，示例假设Tag包含id和name
      properties:
        id:
          type: string
        name:
          type: string
      required:
        - id
        - name
    ShowStaticInfo:
      type: object
      properties:
        Id:  # 和Java类字段名严格匹配（注意大小写）
          type: string
        time:
          type: integer
          format: int64
        poster:
          type: string
          format: uri  # 映射Java的URI类型
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
          uniqueItems: true  # 用uniqueItems模拟Java Set的唯一性特性
        objectCreated:  # 和Java类字段名严格匹配
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Tag'  # 定义Map的值类型为Tag，键默认是string
      # 可根据业务需求添加必填字段列表
      required:
        - Id
        - time

关键修改细节说明： #

1. 字段名一致性：修正了原YAML里和Java类字段不匹配的问题（比如showId改为Id，showObjectCreated改为objectCreated），避免序列化/反序列化时出现字段映射错误。

2. URI类型处理：
   OpenAPI没有专门的URI Schema类型，直接使用type: string + format: uri即可，这是JSON Schema的标准格式，能完美映射Java的java.net.URI类型。

3. Set类型处理：
   在OpenAPI中，Set结构用array类型表示，同时设置uniqueItems: true来强制元素唯一性，完全对应Java Set的核心特性。数组的items指向我们定义的Tag Schema。

4. HashMap<String, Tag>类型处理：
   Map结构在OpenAPI中用type: object + additionalProperties定义。additionalProperties指定Map值的类型为Tag，而JSON对象的键默认是string类型，正好匹配Java的HashMap<String, Tag>。

5. 补充Tag Schema：因为你的Java类依赖Tag类型，必须在components schemas中定义它的结构（示例里的字段是假设的，你可以根据实际的Tag类字段调整）。

内容的提问来源于stack exchange，提问作者peter ivarsson