openapi中如何定义对象中的字段是唯一的？

Question

我有这个 api 文档是用 OpenAPI 3.0.3 编写的

openapi: 3.0.3
info:
  version: '1.0'
  title: 'MyTitle'
  description: Specification for Bear Store

servers:
  - url: https://development.example.com/v1
    description: Development Server

paths:
  '/v1/bears':
    get:
      description: Requests a lists all the bears
      summary: List of bears request
      responses:
        '200':
          description: List of Bears
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                    name:
                      type: string

我有一个 Bear 对象，它具有id, 和name属性。我想定义 id 字段是一个唯一字段。我如何在 OpenAPI 3 中定义它？

Answer 1

OpenAPI 允许您定义字段的类型及其预期格式。但它不可能确保其唯一性。

唯一性是一个业务问题，可能涉及重要的检查。因此，形式化此类概念超出了 OpenAPI/Swagger 的范围。

但是，您可以添加描述来解释字段值必须唯一的要求，然后在 API 中实施必要的检查以确保客户端提供的值实际上是唯一的。